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.gibb...@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.gibb...@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