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

[Martin Buchholz]

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
>