On 04/11/2016 04:12 PM, Martin Buchholz wrote:
On Mon, Apr 11, 2016 at 3:57 PM, Jonathan Gibbons
<[email protected]> 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
