• Java 11: Inherit javadoc from base java classes

    From Stanimir Stamenkov@21:1/5 to All on Sat Oct 2 22:18:18 2021
    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From =?UTF-8?Q?Arne_Vajh=c3=b8j?=@21:1/5 to Stanimir Stamenkov on Sat Oct 2 20:22:04 2021
    On 10/2/2021 3:18 PM, Stanimir Stamenkov wrote:
    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?

    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Stanimir Stamenkov@21:1/5 to All on Sun Oct 3 09:41:35 2021
    Sat, 2 Oct 2021 20:22:04 -0400, /Arne Vajhøj/:
    On 10/2/2021 3:18 PM, Stanimir Stamenkov wrote:

    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?

    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

    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Stanimir Stamenkov@21:1/5 to All on Sun Oct 3 13:30:55 2021
    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Stanimir Stamenkov@21:1/5 to All on Sun Oct 3 14:45:49 2021
    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Stanimir Stamenkov@21:1/5 to All on Sun Oct 3 15:54:47 2021
    Sun, 3 Oct 2021 14:45:49 +0300, /Stanimir Stamenkov/:
    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...

    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

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)