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

[Jonathan Gibbons]

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