RFR: 8152818: Javadoc must support module options supported by javac.

[Kumar Srinivasan]

Martin,

The bug  8152818 was pushed last night, below is a recipe
to build  jsr166's API doc.  Please note, this is not an  optimal
solution, and also encountered a javac issue JDK-8154152,
also we are in discussion on a simpler method to address your
jsr166  and other similar use cases that have been brought to
our attention. Please check if the output is what you expect, I
did not have time to go through the output.

Thanks
Kumar

JDKDIR=<jdk_forest_dir>
JSR166_SRC=./jsr166/src/java.base
JDK_SRC=$JDKDIR/jdk/src/*/share/classes
CORBA_SRC=$JDKDIR/corba/src/*/share/classes
LT_SRC=$JDKDIR/langtools/src/*/share/classes
PLAT_SRC=$JDKDIR/jdk/src/*/unix/classes
GEN_SRC=$JDKDIR/build/linux-x86_64-normal-server-release/support/gensrc/*
JAVA_HOME=$JDKDIR/build/linux-x86_64-normal-server-release/images/jdk

JDK9_SRC=$JDK_SRC:$CORBA_SRC:$LT_SRC:$PLAT_SRC:$GEN_SRC

$JAVA_HOME/bin/javadoc -d  javadoc-out \
   -tag 'apiNote:a:API Note:' \
   -tag 'implSpec:a:Implementation Requirements:' \
   -tag 'implNote:a:Implementation Note:' \
   -tag 'jvms:a:See <cite> The Java™ Virtual Machine 
Specification</cite>:' \
   -tag 'jls:a:See <cite> The Java™ Language Specification</cite>:' \
   -modulesourcepath $JSR166_SRC:$JDK9_SRC \
   java.util \
   java.util.concurrent \
   java.util.concurrent.locks \
   java.util.concurrent.atomic






> I think we can work -modulesourcepath into our build.xml
> CVS has zero support for symlinks, but at build time we can create a
> skeletal directory
> modulesrc/
> modulesrc/java.base -> ${src.dir}
> or if necessary copy the entire tree when running javadoc.
>
> We're reluctant to reorganize our src/main directory because it messes
> with CVS history.
>
> What I'm afraid of is spending several development cycles of you
> trying to get us what we want and it not quite working, when it would
> be faster for you to test directly on a jsr166 CVS checkout.  Create a
> javadoc9 command line that recreates our
> http://gee.cs.oswego.edu/dl/jsr166/dist/docs/
> and jsr166 maintainers can do the rest.
>
> On Mon, Apr 11, 2016 at 4:35 PM, Jonathan Gibbons
> <jonathan.gibbons at oracle.com> wrote:
>>
>> On 04/11/2016 04:12 PM, Martin Buchholz wrote:
>>> On Mon, Apr 11, 2016 at 3:57 PM, Jonathan Gibbons
>>> <jonathan.gibbons at oracle.com> wrote:
>>>>
>>>> On 04/07/2016 10:04 PM, Martin Buchholz wrote:
>>>>> I'm not really qualified, but here are random comments:
>>>>>
>>>>> I think the general idea is right - javac and javadoc need the same
>>>>> kind of support for modules.
>>>>> I worry that details may be different, e.g. javadoc has diamond
>>>>> inheritance and pulls in via @{inheritDoc} part of the
>>>>> "implementation" from module sources.
>>>>
>>>> Can you explain this a bit more?   Is this a new problem in JDK 9,
>>>> with/without modules, or
>>>> is it a pre-existing problem with @inheritDoc ?
>>> This is a pre-existing difference between javadoc and javac.  javadoc
>>> has always had diamond inheritance to support @{inheritDoc}.  (Maybe
>>> javac now also has it to support default methods.)
>>>
>>>>> It would be nice if there was a working sample javadoc command line
>>>>> for jsr166 CVS.
>>>>
>>>> What would you want to be the goal of such a command line?  Would it be
>>>> to
>>>> just
>>>> document the jsr166 classes, or would you want to generate the JavaSE
>>>> docs
>>>> including the latest jsr166 sources?
>>> I maintain the javadoc invocations in
>>> http://gee.cs.oswego.edu/cgi-bin/viewcvs.cgi/jsr166/build.xml?view=markup
>>> that generate
>>> http://gee.cs.oswego.edu/dl/jsr166/dist/docs/
>>> which contains only the javadoc for files in jsr166 CVS.
>>> I'm unsure how we are supposed to generate this in a jigsaw world.
>>> These files are destined to become part of java.base, and they
>>> @{inheritDoc} strings out of java.base sources, but they are also
>>> independent software artifacts.
>>>
>>> It doesn't quite fit into jigsaw.  How do you generate javadoc for a
>>> module subset that lives in a separate source tree?
>>
>>
>> Right now, because you want to "{@inheritDoc} strings out of java.base
>> sources",
>> you would have to put much of the jdk/src repo on the module source path,
>> with
>> your repo in front.     I see you're already doing something like that in
>> the following
>> lines:
>>
>>      <javadoc destdir="${docs.dir}"
>>               packagenames="none"
>>               link="${java9.api.url}"
>>               overview="${src.dir}/intro.html"
>>               access="${build.javadoc.access}"
>>               sourcepath="${src.dir}:${jdk9.src.dir}"
>>               classpath=""
>>               executable="${javadoc9}">
>>
>> but now you need to be using -modulesourcepath, which is (regrettably) a
>> more
>> complex option, since javac and javadoc have to be able to isolate the
>> module
>> name in the filename paths.   Obviously, the jdk9/jdk9/jdk repo has its
>> source
>> organized in a modular layout, but to change to using -modulesourcepath,
>> your own
>> ${src.dir} would have follow the same general rules, which in the simplest
>> case
>> reduces to having a module name (e.g. java.base) above the sources for the
>> packages in that module, e.g.    /path/to/java.base/java/util/*.java
>>