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

classic Classic list List threaded Threaded
16 messages Options
Reply | Threaded
Open this post in threaded view
|

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

Kumar Srinivasan
Hi,

Please review the webrev [1] which fixes [2]. The central theme is, to
dispatch
all javac related options, off to javac's argument processing, so that
it is future
proofed and the arguments are processed correctly as required by javac.

Thanks
Kumar

[1] http://cr.openjdk.java.net/~ksrini/8152818/webrev.00/
[2] https://bugs.openjdk.java.net/browse/JDK-8152818
Reply | Threaded
Open this post in threaded view
|

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

Martin Buchholz-3
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.

It would be nice if there was a working sample javadoc command line
for jsr166 CVS.

add SPC before L
+\  -limitmods <module>(,<module>)* Limit the universe of observable modules\n\




On Thu, Apr 7, 2016 at 6:19 PM, Kumar Srinivasan
<[hidden email]> wrote:

> Hi,
>
> Please review the webrev [1] which fixes [2]. The central theme is, to
> dispatch
> all javac related options, off to javac's argument processing, so that it is
> future
> proofed and the arguments are processed correctly as required by javac.
>
> Thanks
> Kumar
>
> [1] http://cr.openjdk.java.net/~ksrini/8152818/webrev.00/
> [2] https://bugs.openjdk.java.net/browse/JDK-8152818
Reply | Threaded
Open this post in threaded view
|

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

Jonathan Gibbons


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 ?

>
> 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?


>
> add SPC before L
> +\  -limitmods <module>(,<module>)* Limit the universe of observable modules\n\
>
>
>
>
> On Thu, Apr 7, 2016 at 6:19 PM, Kumar Srinivasan
> <[hidden email]> wrote:
>> Hi,
>>
>> Please review the webrev [1] which fixes [2]. The central theme is, to
>> dispatch
>> all javac related options, off to javac's argument processing, so that it is
>> future
>> proofed and the arguments are processed correctly as required by javac.
>>
>> Thanks
>> Kumar
>>
>> [1] http://cr.openjdk.java.net/~ksrini/8152818/webrev.00/
>> [2] https://bugs.openjdk.java.net/browse/JDK-8152818

Reply | Threaded
Open this post in threaded view
|

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

Martin Buchholz-3
On Mon, Apr 11, 2016 at 3:57 PM, Jonathan Gibbons
<[hidden email]> 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?
Reply | Threaded
Open this post in threaded view
|

Re: 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
> <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

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

Martin Buchholz-3
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
<[hidden email]> wrote:

>
>
> On 04/11/2016 04:12 PM, Martin Buchholz wrote:
>>
>> On Mon, Apr 11, 2016 at 3:57 PM, Jonathan Gibbons
>> <[hidden email]> 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
>
Reply | Threaded
Open this post in threaded view
|

Re: 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&trade; Virtual Machine
Specification</cite>:' \
   -tag 'jls:a:See <cite> The Java&trade; 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
> <[hidden email]> wrote:
>>
>> On 04/11/2016 04:12 PM, Martin Buchholz wrote:
>>> On Mon, Apr 11, 2016 at 3:57 PM, Jonathan Gibbons
>>> <[hidden email]> 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
>>

Reply | Threaded
Open this post in threaded view
|

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

Martin Buchholz-3
On Fri, Apr 15, 2016 at 8:17 AM, Kumar Srinivasan
<[hidden email]> wrote:

>
> 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&trade; Virtual Machine
> Specification</cite>:' \
>   -tag 'jls:a:See <cite> The Java&trade; Language Specification</cite>:' \
>   -modulesourcepath $JSR166_SRC:$JDK9_SRC \
>   java.util \
>   java.util.concurrent \
>   java.util.concurrent.locks \
>   java.util.concurrent.atomic

I tried and failed to get any variant of the above to produce any
output at all :(
But I didn't try that hard, because the above appears to try to
produce docs for all of java.util, and we are only interested in a
small subset of java.util.  So we have traditionally provided javadoc
an explicit list of files as input, and want to continue doing that.

I tried a bunch of experiments; details in subsequent messages.
Reply | Threaded
Open this post in threaded view
|

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

Martin Buchholz-3
Below is a script that successfully processes all of the jsr166 source
files, but ignores JDK sources and so all of the {@inheritDoc} are
left blank, which is a regression.

I couldn't find any way to get javadoc to warn me if the {@inheritDoc}
snippets could not be filled in (sort of a "linker error").  You would
think -Xdoclint:all would do that.  Seems like a BUG.

#!/bin/bash
set -eu
JDKSRC=/home/martin/ws/jdk9-dev
JDK=$JDKSRC/build/linux-x86_64-normal-server-release/images/jdk
DIR=bug1
rm -rf $DIR
cvs -Q -d ':pserver:anonymous:@gee.cs.oswego.edu/home/jsr166/jsr166'
checkout -d $DIR jsr166/src/main
cd $DIR

find -name '*.java' |
xargs perl -0777 -pi -e 's~sun\.(reflect|misc)~jdk.internal.$1~g'

exec $JDK/bin/javadoc \
  -d docs \
  -Xdoclint:all \
  -Xmodule:java.base \
  -Xdocrootparent http://docs.oracle.com/javase/9/docs \
  -tag 'jls:a:See <cite> The Java&trade; Language Specification</cite>:' \
  -tag 'implSpec:a:Implementation Requirements:' \
  -tag 'implNote:a:Implementation Note:' \
  $(find java -name '*.java')
Reply | Threaded
Open this post in threaded view
|

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

Martin Buchholz-3
Here's a variant where I try adding -modulesearchpath pointing at the
jdk sources.

It fails with the error

java/util/PriorityQueue.java:26: error: unnamed package is not allowed
in named modules
package java.util;
^

... but that's nonsensical - this is not an unnamed package.  That's
the package statement right there!
Seems like a BUG.

#!/bin/bash
set -eu
JDKSRC=/home/martin/ws/jdk9-dev
JDK=$JDKSRC/build/linux-x86_64-normal-server-release/images/jdk
DIR=bug2
rm -rf $DIR
cvs -Q -d ':pserver:anonymous:@gee.cs.oswego.edu/home/jsr166/jsr166'
checkout -d $DIR jsr166/src/main
cd $DIR

find -name '*.java' |
xargs perl -0777 -pi -e 's~sun\.(reflect|misc)~jdk.internal.$1~g'

exec $JDK/bin/javadoc \
  -d docs \
  -Xdoclint:all \
  -Xmodule:java.base \
  -modulesourcepath "$JDKSRC/jdk/src/java.base/share/classes" \
  -Xdocrootparent http://docs.oracle.com/javase/9/docs \
  -tag 'jls:a:See <cite> The Java&trade; Language Specification</cite>:' \
  -tag 'implSpec:a:Implementation Requirements:' \
  -tag 'implNote:a:Implementation Note:' \
  $(find java -name '*.java')
Reply | Threaded
Open this post in threaded view
|

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

Martin Buchholz-3
If I try to pull in @inheritDoc sources using -sourcepath instead of
-modulesourcepath, I get

java/util/ArrayPrefixHelpers.java:7: error: illegal combination of
-Xmodule and module-info on classpath
package java.util;
^
java.lang.AssertionError
at com.sun.tools.javac.util.Assert.error(jdk.compiler@9-internal/Assert.java:155)
at com.sun.tools.javac.util.Assert.checkNull(jdk.compiler@9-internal/Assert.java:54)
at com.sun.tools.javac.code.Symtab.enterModule(jdk.compiler@9-internal/Symtab.java:755)
at com.sun.tools.javac.comp.Modules.enterModule(jdk.compiler@9-internal/Modules.java:257)
at com.sun.tools.javac.comp.Modules.enterModules(jdk.compiler@9-internal/Modules.java:235)
at com.sun.tools.javac.comp.Modules.enter(jdk.compiler@9-internal/Modules.java:203)
at com.sun.tools.javac.main.JavaCompiler.readSourceFile(jdk.compiler@9-internal/JavaCompiler.java:816)
at com.sun.tools.javac.main.JavaCompiler.readSourceFile(jdk.compiler@9-internal/JavaCompiler.java:778)
at com.sun.tools.javac.main.JavaCompiler.access$100(jdk.compiler@9-internal/JavaCompiler.java:97)
at com.sun.tools.javac.main.JavaCompiler$1.complete(jdk.compiler@9-internal/JavaCompiler.java:339)
at com.sun.tools.javac.code.ClassFinder.fillIn(jdk.compiler@9-internal/ClassFinder.java:362)
at com.sun.tools.javac.code.ModuleFinder.lambda$findSingleModule$0(jdk.compiler@9-internal/ModuleFinder.java:206)
at com.sun.tools.javac.code.Symbol.complete(jdk.compiler@9-internal/Symbol.java:602)
at com.sun.tools.javac.comp.Modules.setCompilationUnitModules(jdk.compiler@9-internal/Modules.java:361)
at com.sun.tools.javac.comp.Modules.enter(jdk.compiler@9-internal/Modules.java:205)
at jdk.javadoc.internal.tool.JavadocTool.getEnvironment(jdk.javadoc@9-internal/JavadocTool.java:190)
at jdk.javadoc.internal.tool.Start.parseAndExecute(jdk.javadoc@9-internal/Start.java:403)
at jdk.javadoc.internal.tool.Start.begin(jdk.javadoc@9-internal/Start.java:276)
at jdk.javadoc.internal.tool.Start.begin(jdk.javadoc@9-internal/Start.java:222)
at jdk.javadoc.internal.tool.Main.execute(jdk.javadoc@9-internal/Main.java:70)
at jdk.javadoc.internal.tool.Main.main(jdk.javadoc@9-internal/Main.java:52)

It's not completely clear to me that the combination should be a fatal error.

The module-info is found on the sourcepath, not the classpath; that
seems like a BUG in the message text.

Of course the AssertionError is also a BUG.

#!/bin/bash
set -eu
JDKSRC=/home/martin/ws/jdk9-dev
JDK=$JDKSRC/build/linux-x86_64-normal-server-release/images/jdk
DIR=bug3
rm -rf $DIR
cvs -Q -d ':pserver:anonymous:@gee.cs.oswego.edu/home/jsr166/jsr166'
checkout -d $DIR jsr166/src/main
cd $DIR

find -name '*.java' |
xargs perl -0777 -pi -e 's~sun\.(reflect|misc)~jdk.internal.$1~g'

exec $JDK/bin/javadoc \
  -d docs \
  -Xdoclint:all \
  -Xmodule:java.base \
  -sourcepath "$JDKSRC/jdk/src/java.base/share/classes" \
  -Xdocrootparent http://docs.oracle.com/javase/9/docs \
  -tag 'jls:a:See <cite> The Java&trade; Language Specification</cite>:' \
  -tag 'implSpec:a:Implementation Requirements:' \
  -tag 'implNote:a:Implementation Note:' \
  $(find java -name '*.java')
Reply | Threaded
Open this post in threaded view
|

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

Martin Buchholz-3
A final and successful (but disappointing) experiment.

Copying the JDK sources, deleting the module-info.java file and using
the traditional -sourcepath flag with that brings success.
It's disappointing because it's clearly an ugly hack and retreating to
a pre-jigsaw world (but -Xmodule:java.base works!)

We get annoying warnings from files that are not involved in this compilation,

sourcepath/java/util/GregorianCalendar.java:3231: warning: no @throws
for java.lang.ClassNotFoundException
    private void readObject(ObjectInputStream stream)

but that seems like a pre-existing BUG (jdk8 has it too)
(why, oh why, is javadoc wasting its time analyzing GregorianCalendar.java?)

#!/bin/bash
set -eu
JDKSRC=/home/martin/ws/jdk9-dev
JDK=$JDKSRC/build/linux-x86_64-normal-server-release/images/jdk
DIR=bug4
rm -rf $DIR
cvs -Q -d ':pserver:anonymous:@gee.cs.oswego.edu/home/jsr166/jsr166'
checkout -d $DIR jsr166/src/main
cd $DIR

find -name '*.java' |
xargs perl -0777 -pi -e 's~sun\.(reflect|misc)~jdk.internal.$1~g'

rsync -a "$JDKSRC/jdk/src/java.base/share/classes/" sourcepath/
rm sourcepath/module-info.java

exec $JDK/bin/javadoc \
  -d docs \
  -Xdoclint:all \
  -Xmodule:java.base \
  -sourcepath "sourcepath" \
  -Xdocrootparent http://docs.oracle.com/javase/9/docs \
  -tag 'jls:a:See <cite> The Java&trade; Language Specification</cite>:' \
  -tag 'implSpec:a:Implementation Requirements:' \
  -tag 'implNote:a:Implementation Note:' \
  $(find java -name '*.java')
Reply | Threaded
Open this post in threaded view
|

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

Martin Buchholz-3
One more non-gripe!
If I leave the references to sun.misc.Unsafe (instead of the
jdk.internal variant) I get:

java/util/concurrent/atomic/AtomicLong.java:28: error: package
sun.misc does not exist
    private static final sun.misc.Unsafe U = sun.misc.Unsafe.getUnsafe();

But I notice that the architected
  -XaddReads:java.base=jdk.unsupported \
succeeds in removing it.

#!/bin/bash
set -eu
JDKSRC=/home/martin/ws/jdk9-dev
JDK=$JDKSRC/build/linux-x86_64-normal-server-release/images/jdk
DIR=bug5
rm -rf $DIR
cvs -Q -d ':pserver:anonymous:@gee.cs.oswego.edu/home/jsr166/jsr166'
checkout -d $DIR jsr166/src/main
cd $DIR

find -name '*.java' |
xargs perl -0777 -pi -e 's~sun\.(reflect)~jdk.internal.$1~g'

rsync -a "$JDKSRC/jdk/src/java.base/share/classes/" sourcepath/
rm sourcepath/module-info.java

exec $JDK/bin/javadoc \
  -d docs \
  -Xdoclint:all \
  -Xmodule:java.base \
  -XaddReads:java.base=jdk.unsupported \
  -sourcepath "sourcepath" \
  -Xdocrootparent http://docs.oracle.com/javase/9/docs \
  -tag 'jls:a:See <cite> The Java&trade; Language Specification</cite>:' \
  -tag 'implSpec:a:Implementation Requirements:' \
  -tag 'implNote:a:Implementation Note:' \
  $(find java -name '*.java')
Reply | Threaded
Open this post in threaded view
|

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

Jonathan Gibbons
In reply to this post by Martin Buchholz-3


On 04/16/2016 03:45 PM, Martin Buchholz wrote:
> exec $JDK/bin/javadoc \
>    -d docs \
>    -Xdoclint:all \
>    -Xmodule:java.base \
>    -modulesourcepath "$JDKSRC/jdk/src/java.base/share/classes" \

javadoc folk,

This looks like a bug.  Assuming Martin is using reasonably up to date
JDK 9 code, you should not be able to specify both -Xmodule and
-modulesourcepath.

-- Jon
Reply | Threaded
Open this post in threaded view
|

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

Martin Buchholz-3
On Mon, Apr 18, 2016 at 11:11 AM, Jonathan Gibbons
<[hidden email]> wrote:

>
>
> On 04/16/2016 03:45 PM, Martin Buchholz wrote:
>>
>> exec $JDK/bin/javadoc \
>>    -d docs \
>>    -Xdoclint:all \
>>    -Xmodule:java.base \
>>    -modulesourcepath "$JDKSRC/jdk/src/java.base/share/classes" \
>
>
> javadoc folk,
>
> This looks like a bug.  Assuming Martin is using reasonably up to date JDK 9
> code, you should not be able to specify both -Xmodule and -modulesourcepath.

What I'm trying to tell javadoc is that I have some source files that
are logically in the java.base module, and they override (and inherit
from) the full module sources (including module-info.java) that are
somewhere else (in a jdk9 source tree).
Reply | Threaded
Open this post in threaded view
|

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

Jonathan Gibbons


On 04/18/2016 11:33 AM, Martin Buchholz wrote:

> On Mon, Apr 18, 2016 at 11:11 AM, Jonathan Gibbons
> <[hidden email]> wrote:
>>
>> On 04/16/2016 03:45 PM, Martin Buchholz wrote:
>>> exec $JDK/bin/javadoc \
>>>     -d docs \
>>>     -Xdoclint:all \
>>>     -Xmodule:java.base \
>>>     -modulesourcepath "$JDKSRC/jdk/src/java.base/share/classes" \
>>
>> javadoc folk,
>>
>> This looks like a bug.  Assuming Martin is using reasonably up to date JDK 9
>> code, you should not be able to specify both -Xmodule and -modulesourcepath.
> What I'm trying to tell javadoc is that I have some source files that
> are logically in the java.base module, and they override (and inherit
> from) the full module sources (including module-info.java) that are
> somewhere else (in a jdk9 source tree).


Yes, I understand your intent, and agree it should be possible to do what
you want, in a reasonable way.  We're still trying to figure out the best
way to address your goals.

I was simply noticing/reporting a bug in the tools that allowed you to
specify an
unreasonable combination of options.

-- Jon