building javadoc with modules

[Jonathan Gibbons]

Justin,

This ought to be simple, but as you discovered, it isn't.

I tried to generate the docs using the JDK 10 src.zip, available here:
https://download.java.net/openjdk/jdk10/ri/openjdk-10_src.zip

After ou unzip the sources, the command ought to be as simple as 
something like the following:

/opt/jdk/10/bin/javadoc \
     --module-source-path 'openjdk/src/*/{linux,unix,share}/classes' \
     -d api \
     --expand-requires transitive \
     --module java.se

Here's what those lines mean:

/opt/jdk/10/bin/javadoc \# path to javadoc
     --module-source-path 'openjdk/src/*/{linux,unix,share}/classes' \# 
specify "pattern" for location of sources
     -d api \ # output directory
     --expand-requires transitive \ #saves typing lots of module names
     --module java.se # the root module name (plus its transitive 
dependencies)

Note: the combination of --module java.se --expand-requires transitive 
will just give you the java.* modules (because java.se does not depend 
on any jdk.* modules); if you want the JDK modules as well, you'll have 
to list them separately,

So what's the problem?

If you run the command, it gives lots of "cannot find symbol" messages 
for a comparatively small number of types. The most frequent one that 
showed up for me was java.nio.ByteBuffer ... and therein lies the hint 
of the problem. There is no source for java.nio.ByteBuffer in the 
src.zip file! It turns out that for a number of classes, including 
{Byte,Char}Buffer, Charset{De,En}coder, the source is generated as part 
of the full JDK build.

There are two possible workarounds:

1. Run the full build first, then figure out the path to the gensrc 
directory. For my system, it is something like
         build/linux-x86_64-normal-server-release/support/gensrc/
     meaning that the --module-source-path option has to be something like:

-module-source-path 
'openjdk/src/*/{linux,unix,share}/classes:build/linux-x86_64-normal-server-release/support/gensrc/*'

     If you're looking to generate full docs for all of Java SE, this is 
the recommended solution, but if you're going to build JDK, then you 
might as well use the JDK makefiles to build the docs as well, with just 
"make docs" or "make docs-jdk-api" or something like that.

2. The other option is much more verbose, and not recommended if you're 
trying to generate full documentation for Java SE.
It relies on the fact that the definitions for the missing symbols do 
exist in JDK itself, for the right version of JDK. So you can use the 
--patch-module option to "patch" every module you want to document with 
its source code.  If you're looking to modify one or a few modules, and 
generate updated docs, this may be a reasonable approach, but if you're 
looking to generate docs for all 72 JDK modules, that's a long command 
line! You will still need the basic --module-source-path option, to keep 
javadoc happy and to tell it that you're working in "multi-module mode", 
but you won't need to provide the gensrc directory.

The alternative is to find/use a consolidated src.zip file that (just) 
contains all the source for your platform, and nothing else, in a single 
simple exploded module hierarchy.

-- Jon


On 08/27/2018 06:47 PM, Justin Lee wrote:
> I'm trying to runjavadocagainst the java9 src.zip and I have no idea 
> how to handle the modules.  Even if I go with the classic 
> "javadoc at sources" approach I get an error about too many modules 
> defined.  I've tried a number of variations but I can't quite seem to 
> crack that nut.
>
> My latest attempt looks like this:
>
>     javadoc -d /tmp/javadoc9 -html5 --module \
>          java.management.rmi \
>      jdk.packager.services \
>      jdk.scripting.nashorn.shell \
>          <more module names here...> \
>          -Xmaxerrs 1000 \
>          @source.files
>
>
>
> Does anyone have an example of running thejavadoctool from the command 
> line and generating docs for modularized code like this?  Thanks.
>
> -- 
> You can find me on the net at:
> http://antwerkz.com <http://antwerkz.com/> http://antwerkz.com/+
> http://antwerkz.com/twitter http://antwerkz.com/github

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20180829/0bedcf11/attachment.html>