Java 11: Inherit javadoc from base java classes

16 views
Skip to first unread message

Stanimir Stamenkov

unread,
Oct 2, 2021, 3:18:31 PM10/2/21
to
I have the following source:

src/net/example/FooOp.java

-----FooOp.java
package net.example;

import java.awt.RenderingHints;
import java.awt.geom.Point2D;
import java.awt.geom.Rectangle2D;
import java.awt.image.BufferedImage;
import java.awt.image.BufferedImageOp;
import java.awt.image.ColorModel;

public class FooOp implements BufferedImageOp {

@Override
public BufferedImage filter(BufferedImage src, BufferedImage dest) {
return null;
}

@Override
public Rectangle2D getBounds2D(BufferedImage src) {
return null;
}

@Override
public BufferedImage createCompatibleDestImage(BufferedImage src,
ColorModel destCM) {
return null;
}

@Override
public Point2D getPoint2D(Point2D srcPt, Point2D dstPt) {
return null;
}

@Override
public RenderingHints getRenderingHints() {
return null;
}

}
-----FooOp.java--

I'm trying to generate javadoc for the given source while inheriting
apidoc from the base class/interface which happens to be from the
standard Java library.

I have the following "options" file (I'm on Windows for what is worth):

net.example
-d
doc
-sourcepath
src;C:\java\jdk-11\src
-link
https://docs.oracle.com/en/java/javase/11/docs/api

I have extracted the "src.zip" in the "C:\java\jdk-11" installation to a
"src" subdirectory just for that purpose.

I'm executing:

> javadoc @options

but I'm not getting the generated javadoc inheriting apidoc from the jdk
sources.

The same example using Java 8 javadoc, and options:

net.example
-d
doc
-sourcepath
src;C:\java\jdk1.8.0\src
-link
https://docs.oracle.com/javase/8/docs/api

works as expected. What configuration I need to use to make the same
working with Java 11's javadoc?

--
Stanimir

Arne Vajhøj

unread,
Oct 2, 2021, 8:22:24 PM10/2/21
to
I suspect that you may need to add the module name to the source
path for Java 11:

-sourcepath
src;C:\java\jdk-11\src\java.desktop

Arne

Stanimir Stamenkov

unread,
Oct 3, 2021, 2:41:51 AM10/3/21
to
Sat, 2 Oct 2021 20:22:04 -0400, /Arne Vajhøj/:
Thanks for chiming in. With this setup I'm getting mixed results:

>javadoc @options
Loading source files for package net.example...
Constructing Javadoc information...
Creating destination directory: "doc\"
Standard Doclet version 11.0.12
Building tree for all the packages and classes...
Generating doc\java.desktop\net\example\FooOp.html...
Generating doc\java.desktop\net\example\package-summary.html...
Generating doc\java.desktop\net\example\package-tree.html...
Generating doc\java.desktop\module-summary.html...
C:\java\jdk-11\src\java.desktop\module-info.java:48: error: unknown tag:
moduleGraph
* @moduleGraph
^
Generating doc\constant-values.html...
Building index for all the packages and classes...
Generating doc\overview-tree.html...
Generating doc\index-all.html...
Building index for all classes...
Generating doc\allclasses-index.html...
Generating doc\allpackages-index.html...
Generating doc\deprecated-list.html...
Building index for all classes...
Generating doc\allclasses.html...
Generating doc\allclasses.html...
Generating doc\index.html...
Generating doc\help-doc.html...
1 error

I'm getting the javadoc inherited but my package gets included in the
"java.desktop" module. I've tried next:

>javac -d classes src\net\example\FooOp.java

and adding to the javadoc options:

-classpath
classes

>javadoc @options
Loading source files for package net.example...
Constructing Javadoc information...
Note: Multiple elements named 'net.example' in modules 'java.desktop,
unnamed module' were found by
javax.lang.model.util.Elements.getPackageElement.
javadoc: warning - Package net.example not found
javadoc: error - No public or protected classes found to document.
1 error
1 warning

(no doc generated at all)

I'll further try adding a module descriptor for my source, though my
goal is dealing with unnamed module sources.

--
Stanimir

Stanimir Stamenkov

unread,
Oct 3, 2021, 6:31:10 AM10/3/21
to
Sun, 3 Oct 2021 09:41:35 +0300, /Stanimir Stamenkov/:

> I'll further try adding a module descriptor for my source, though my
> goal is dealing with unnamed module sources.

Added src/module-info.java

-----module-info.java
module net.example {

requires transitive java.desktop;

exports net.example;

}
-----module-info.java--

Using the same "options":

net.example
-d
doc
-sourcepath
src;C:\java\jdk-11\src\java.desktop
-link
https://docs.oracle.com/en/java/javase/11/docs/api

now I'm _not_ getting the javadoc inherited.

I've further tried:

>xcopy /s /i src src-modules\net.example

so now I'm having source like:

src-modules/
net.nexample/
module-info.java
net/example/
FooOp.java

then having javadoc @options:

--module
net.example
-d
doc
--module-source-path
src-module;C:\java\jdk-11\src
-link
https://docs.oracle.com/en/java/javase/11/docs/api

but I'm getting lots of errors related to java.base classes:

Constructing Javadoc information...
C:\java\jdk-11\src\java.base\jdk\internal\access\SharedSecrets.java:28:
error: package javax.crypto does not exist
import javax.crypto.SealedObject;
^
C:\java\jdk-11\src\java.base\jdk\internal\access\JavaxCryptoSealedObjectAccess.java:27:
error: package javax.crypto does not exist
import javax.crypto.BadPaddingException;
^
...

and finally no doc produced.

Has anyone successfully generated javadoc with inherited doc from base
Java 11 classes?

--
Stanimir

Stanimir Stamenkov

unread,
Oct 3, 2021, 7:46:02 AM10/3/21
to
Sun, 3 Oct 2021 13:30:55 +0300, /Stanimir Stamenkov/:

>   src-modules/
>     net.nexample/
>       module-info.java
>       net/example/
>         FooOp.java
>
> then having javadoc @options:
>
> --module
> net.example
> -d
> doc
> --module-source-path
> src-module;C:\java\jdk-11\src
^
src-modules (same outcome, anyway)

> -link
> https://docs.oracle.com/en/java/javase/11/docs/api
>
> but I'm getting lots of errors related to java.base classes:
>
> Constructing Javadoc information...
> C:\java\jdk-11\src\java.base\jdk\internal\access\SharedSecrets.java:28:
> error: package javax.crypto does not exist
> import javax.crypto.SealedObject;
>                    ^
> C:\java\jdk-11\src\java.base\jdk\internal\access\JavaxCryptoSealedObjectAccess.java:27:
> error: package javax.crypto does not exist
> import javax.crypto.BadPaddingException;
>                    ^
> ...
>
> and finally no doc produced.
>
> Has anyone successfully generated javadoc with inherited doc from base
> Java 11 classes?

O.k. I've been able to generate the desired result by linking
C:\java\jdk-11\src\java.desktop as src-modules\java.desktop, and javadoc
options:

--module
net.example
-d
doc
--module-source-path
src-modules
-link
https://docs.oracle.com/en/java/javase/11/docs/api

It would be nice if one could just use the complete jdk sources.

Now I'm wondering if I could achieve similar result but for unnamed
module sources (without associating them to another module).

--
Stanimir

Stanimir Stamenkov

unread,
Oct 3, 2021, 8:55:02 AM10/3/21
to
Sun, 3 Oct 2021 14:45:49 +0300, /Stanimir Stamenkov/:
> C:\java\jdk-11\src\java.desktop as src-modules\java.desktop...

However this still doesn't work if I want to inherit doc from java.base,
f.e. implementing java.util.Iterator having the methods inherit its
parameters and returns documentation.

--
Stanimir
Reply all
Reply to author
Forward
0 new messages