Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.java.programmer > #39706 > unrolled thread

Java 11: Inherit javadoc from base java classes

Back to article view | Back to comp.lang.java.programmer

Contents

  Java 11: Inherit javadoc from base java classes Stanimir Stamenkov <s7an10@netscape.net> - 2021-10-02 22:18 +0300
    Re: Java 11: Inherit javadoc from base java classes Arne Vajhøj <arne@vajhoej.dk> - 2021-10-02 20:22 -0400
      Re: Java 11: Inherit javadoc from base java classes Stanimir Stamenkov <s7an10@netscape.net> - 2021-10-03 09:41 +0300
        Re: Java 11: Inherit javadoc from base java classes Stanimir Stamenkov <s7an10@netscape.net> - 2021-10-03 13:30 +0300
          Re: Java 11: Inherit javadoc from base java classes Stanimir Stamenkov <s7an10@netscape.net> - 2021-10-03 14:45 +0300
            Re: Java 11: Inherit javadoc from base java classes Stanimir Stamenkov <s7an10@netscape.net> - 2021-10-03 15:54 +0300

#39706 — Java 11: Inherit javadoc from base java classes

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

[toc] | [next] | [standalone]

#39707

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

[toc] | [prev] | [next] | [standalone]

#39708

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

[toc] | [prev] | [next] | [standalone]

#39709

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

[toc] | [prev] | [next] | [standalone]

#39710

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

[toc] | [prev] | [next] | [standalone]

#39711

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

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.java.programmer

csiph-web