• Type: Bug
• Component: tools
• Sub-Component: javadoc(tool)
• Affected Version: 9

• Priority: P3
• Status: Resolved
• Resolution: Duplicate

• Submitted: 2015-09-14
• Updated: 2017-02-01
• Resolved: 2017-02-01

JDK 9
9Resolved

I can't reproduce the head-scratcher. I've tried back to b150. Given that the code that would have generated the head-scratcher message has been rewritten, I think we should set that quirk aside until such time as it may occur again, in which case a more complete test case would help. Arguably we should have a P4 RFE (for JDK 10) to either allow or warn about putting zip files like src.zip on the module source path. The use case for javac is not very compelling; the use case for javadoc is more interesting. JDK-8173782. Finally, I'm going to close this as a dup of JDK-8173777. 01-02-2017 I tried the command-line version of putting src.zip on the module source path, and got a reasonable error message: ./build/linux-x86_64-normal-server-release/images/jdk/bin/javadoc --module-source-path build/linux-x86_64-normal-server-release/images/jdk/lib/src.zip -d play/tmp.zip-on-module-source-path java.util Loading source files for package java.util... javadoc: error - No source files for package java.util 1 error 01-02-2017 I've linked this to JDK-8173777 with the expectation that it will end up closed as a duplicate, or some similar disposition. For now, the only item holding this open is Martin's head-scratcher, until I can find the JBS issue that addressed that. The error message looks related to JDK-8165102. 01-02-2017 Yes, "ant docs" in jsr166 works well and uses the -Xmodule flag; nothing is blocking us. Feel free to close this bug. But as Jonathan suggests, javadoc maintainers should check whether older bad behavior I encountered is still around. 01-02-2017 We should check out Martin's head-scratcher from 2016-12-08 13:51 as a separate issue. I think we fixed it but would like to make sure. 01-02-2017 I tested jsr-166 last week, and everything seems to work. Can you please verify. I would like to close this out. 01-02-2017 We can surely generate the javadoc for our project eventually; at worst we can copy our sources into a copy of the jdk sources and run javadoc inside that. But I'm resisting implementing that for now because ours seems like a valid use case and the AssertionErrors should all get fixed. 09-12-2016 I tried the plausible <arg line="--module-source-path ${jdk9.home}/src.zip"/> and got the head-scratcher error below: [javadoc] /home/martin/jsr166/jigsaw/src/main/java/util/AbstractQueue.java:7: error: unnamed package is not allowed in named modules [javadoc] package java.util; [javadoc] ^ 08-12-2016 src.zip is now internally organized by module. That implies you should unzip it, and either put the sources for java.base on the sourcepath or you should put the entire unpacked directory on the module source path, along with your sources. I'll maybe try something out and get back to you. 08-12-2016 > Hasn't src.zip always been available? Maybe that is the "compiled form" you are looking for ;-) Huh... It had never occurred to me to use src.zip. Probably had an Id��e fixe that src.zip only gets used by IDEs. So I tried: <javadoc ... sourcepath="${src.dir}::${jdk9.home}/src.zip" and got: [javadoc] Skipping /home/martin/ws/jdk9-dev/build/linux-x86_64-normal-server-release/images/jdk/src.zip since it is no directory. Hmmm... well maybe that's a deficiency in the javadoc ant task. OK let's try: <arg line="-sourcepath ${src.dir}:${jdk9.home}/src.zip"/> and that SUCCEEDED, but had no effect ... presumably because the layout has changed; actual source files inside the jar are segregated by module, and javadoc isn't taking that into account. So I'm still stuck. 08-12-2016 I tried again today (with jigsaw refresh) to add the JDK sources to my sourcepath, and still get [javadoc] /home/martin/jdk/src/jdk9/jdk/src/java.base/share/classes/module-info.java:29: error: illegal combination of -Xmodule and module-info on sourcepath [javadoc] module java.base { [javadoc] ^ [javadoc] error: cannot access module-info [javadoc] cannot resolve modules [javadoc] javadoc: error - fatal error encountered: java.lang.AssertionError [javadoc] javadoc: error - Please file a bug against the javadoc tool via the Java bug reporting page [javadoc] (http://bugreport.java.com) after checking the Bug Database (http://bugs.java.com) [javadoc] for duplicates. Include error messages and the following diagnostic in your report. Thank you. [javadoc] java.lang.AssertionError [javadoc] at jdk.compiler/com.sun.tools.javac.util.Assert.error(Assert.java:155) [javadoc] at jdk.compiler/com.sun.tools.javac.util.Assert.check(Assert.java:46) [javadoc] at jdk.compiler/com.sun.tools.javac.comp.Modules.enter(Modules.java:243) [javadoc] at jdk.javadoc/jdk.javadoc.internal.tool.JavadocTool.getEnvironment(JavadocTool.java:194) [javadoc] at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:591) [javadoc] at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:424) [javadoc] at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:341) [javadoc] at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:63) [javadoc] at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:52) [javadoc] 4 errors 08-12-2016 Hasn't src.zip always been available? Maybe that is the "compiled form" you are looking for ;-) 08-12-2016 Thanks for confirming that sources are necessary for @inheritDoc. But the "obvious" way is to think of javadoc as just a compiler, and any user just needs the compiled output. We already use -link, so in principle javadoc does have access to the text we would like to inherit, only in "compiled" html form. But yes, any action here would be a major redesign. Reading the javadoc reference page, I now see clearly """Note: The source file for an inherited method must be on the path specified by the -sourcepath option for the documentation comment to be available to copy.""" So ... "never mind". Hmmmm.... what did people do in the dark ages before the jdk sources were made available?! 08-12-2016 >>Are users really expected to run javadoc with a copy of the openjdk sources available, to make @inheritDoc work? If so, this should be documented. I don't see how this could work any other way, short of exporting the comments in some reusable format which would be a major feature update for javadoc. 08-12-2016 Should we open another separate bug about supporting @inheritDoc in any user javadoc that subclasses JDK classes? I don't know how this is even intended to work. Are users really expected to run javadoc with a copy of the openjdk sources available, to make @inheritDoc work? If so, this should be documented. Modules should never get in the way of consuming public ("exported") javadoc. 08-12-2016 DefaultLoggerFinder.java is being looked at because of "Uses", there might be other reasons why javadoc might look at "unrelated" sources/classes, see JDK-8161255 30-08-2016 I tried an experiment, moving that troublesome jdk/src/java.base/share/classes/module-info.java aside. Then "ant docs" failed with: [javadoc] /home/martin/jdk/src/jdk9/jdk/src/java.base/share/classes/jdk/internal/logger/DefaultLoggerFinder.java:45: error: reference not found [javadoc] * sun.util.logging.internal.LoggingProviderImpl which is annoying, because I never asked to run javadoc on that file - why is it even looking at that file? jsr166 itself does not use logging. I then moved jdk/src/java.base/share/classes/module-info.java aside as well, and added ${jdk9.src.home}/jdk/src/java.logging/share/classes to my sourcepath. ... and that succeeded! I can develop this into a long-lived ant hack, but I would prefer if javadoc was more reasonable. 30-08-2016 > 1. {@inheritdoc} pulling in source/content to include in the jsr166 API docs I've never really understood how this is supposed to work. Any user implementation of a java.util Collection is likely to want to inherit some doc using @inheritDoc. But for that you need the sources! Do people really pull down the openjdk sources so that they can get their @inheritDoc right? Anyways, jsr166's needs here are no different from any other java software, except that they are themselves incorporated into java.base, and are using @inheritDoc from "their own module" but in another source tree. Why not first ensure that third party Collection implementations with @inheritDoc work? > 2. References from the jsr166 API docs to the rest of the JDK docs, e.g. with @see @link This is working well! Using -link http://download.java.net/java/jdk9/docs/api/ 30-08-2016 Another day: another crash :-( sorry about that. It's interesting/notable that the problem was not noticed until /home/martin/jsr166/rosa/src/main/java/util/AbstractQueue.java:7. I would have expected the clash to have been determined earlier, before any regular compilation units were analyzed. 30-08-2016 Thanks for the update. What is your expectation of how your jsr166 javadoc will reference the rest of the JDK 9 doc. I guess there's two parts to this: 1. {@inheritdoc} pulling in source/content to include in the jsr166 API docs 2. References from the jsr166 API docs to the rest of the JDK docs, e.g. with @see @link 30-08-2016 An attempt to add jdk9 sources back in - sourcepath="${src.dir}" + sourcepath="${src.dir}:${jdk9.src.dir}" -sourcepath /home/martin/jsr166/rosa/src/main:/home/martin/jdk/src/jdk9/jdk/src/java.base/share/classes results in: [javadoc] /home/martin/jsr166/rosa/src/main/java/util/AbstractQueue.java:7: error: illegal combination of -Xmodule and module-info on classpath [javadoc] package java.util; [javadoc] ^ [javadoc] java.lang.AssertionError [javadoc] at com.sun.tools.javac.util.Assert.error(jdk.compiler@9-ea/Assert.java:155) [javadoc] at com.sun.tools.javac.util.Assert.checkNull(jdk.compiler@9-ea/Assert.java:54) [javadoc] at com.sun.tools.javac.code.Symtab.enterModule(jdk.compiler@9-ea/Symtab.java:755) [javadoc] at com.sun.tools.javac.comp.Modules.enterModule(jdk.compiler@9-ea/Modules.java:300) [javadoc] at com.sun.tools.javac.comp.Modules.enterModules(jdk.compiler@9-ea/Modules.java:278) [javadoc] at com.sun.tools.javac.comp.Modules.enter(jdk.compiler@9-ea/Modules.java:246) [javadoc] at com.sun.tools.javac.comp.Modules.enter(jdk.compiler@9-ea/Modules.java:229) [javadoc] at com.sun.tools.javac.main.JavaCompiler.readSourceFile(jdk.compiler@9-ea/JavaCompiler.java:817) [javadoc] at com.sun.tools.javac.main.JavaCompiler.readSourceFile(jdk.compiler@9-ea/JavaCompiler.java:779) [javadoc] at com.sun.tools.javac.main.JavaCompiler.access$100(jdk.compiler@9-ea/JavaCompiler.java:98) [javadoc] at com.sun.tools.javac.main.JavaCompiler$1.complete(jdk.compiler@9-ea/JavaCompiler.java:340) [javadoc] at com.sun.tools.javac.code.ClassFinder.fillIn(jdk.compiler@9-ea/ClassFinder.java:361) [javadoc] at com.sun.tools.javac.code.ModuleFinder.lambda$findSingleModule$0(jdk.compiler@9-ea/ModuleFinder.java:206) [javadoc] at com.sun.tools.javac.code.Symbol.complete(jdk.compiler@9-ea/Symbol.java:610) [javadoc] at com.sun.tools.javac.comp.Modules.setCompilationUnitModules(jdk.compiler@9-ea/Modules.java:404) [javadoc] at com.sun.tools.javac.comp.Modules.enter(jdk.compiler@9-ea/Modules.java:248) [javadoc] at com.sun.tools.javac.comp.Modules.initModules(jdk.compiler@9-ea/Modules.java:214) [javadoc] at jdk.javadoc.internal.tool.ElementsTable.scanSpecifiedItems(jdk.javadoc@9-ea/ElementsTable.java:406) [javadoc] at jdk.javadoc.internal.tool.JavadocTool.getEnvironment(jdk.javadoc@9-ea/JavadocTool.java:181) [javadoc] at jdk.javadoc.internal.tool.Start.parseAndExecute(jdk.javadoc@9-ea/Start.java:406) [javadoc] at jdk.javadoc.internal.tool.Start.begin(jdk.javadoc@9-ea/Start.java:295) [javadoc] at jdk.javadoc.internal.tool.Start.begin(jdk.javadoc@9-ea/Start.java:239) [javadoc] at jdk.javadoc.internal.tool.Main.execute(jdk.javadoc@9-ea/Main.java:63) [javadoc] at jdk.javadoc.internal.tool.Main.main(jdk.javadoc@9-ea/Main.java:52) [javadoc] javadoc: error - fatal error Aside from the crash, javadoc should probably be complaining about module-info on sourcepath, not classpath 30-08-2016 I tried again, and found I can make lots of progress with: Index: build.xml =================================================================== RCS file: /export/home/jsr166/jsr166/jsr166/build.xml,v retrieving revision 1.215 diff -u -r1.215 build.xml --- build.xml 29 Aug 2016 23:38:30 -0000 1.215 +++ build.xml 29 Aug 2016 23:54:38 -0000 @@ -432,12 +432,13 @@ <!-- the packagenames="none" hack below prevents scanning the --> <!-- sourcepath for packages --> +<!-- sourcepath="${src.dir}:${jdk9.src.dir}" --> <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}" + sourcepath="${src.dir}" classpath="" executable="${javadoc9}"> <fileset dir="${src.dir}" defaultexcludes="yes"> @@ -446,7 +447,7 @@ <arg line="-Xdocrootparent ${java9.docroot.url}"/> <arg line="-Xmaxerrs 1000 -Xmaxwarns 1000"/> <arg value="-XDignore.symbol.file=true"/> -<!-- TODO <arg value="-Xmodule:java.base"/> --> + <arg value="-Xmodule:java.base"/> <arg value="-tag"/> <arg value="${javadoc.jls.option}"/> <arg value="-tag"/> which generates highly usable javadocs; the only thing apparently missing is @inheritDoc pointing at jdk9 sources, since javadoc won't let me add module sources to my command line. This mostly unblocks the jsr166 project, but there is more work to be done on javadoc. 30-08-2016 Yes, this is (still) an open issue, which has until recently been blocked by https://bugs.openjdk.java.net/browse/JDK-8159305 now fixed with http://hg.openjdk.java.net/jdk9/dev/langtools/rev/81692f730015 29-08-2016 Perhaps the internal error we see isn't getting fixed because it doesn't have a separate bug? I'll file one. In the meantime, the world still needs guidance on the supported way to run javadoc on a set of source files that are part of a module but are being processed separately from the other source files in the module. 29-08-2016 I would like, at a minimum, to see a test case added for javadoc to cover the jsr166 use case. 04-08-2016 In the meantime, I see javadoc -X does include documentation for -Xmodule, so maybe this bug can be closed (done?) but we still see an internal error running javadoc on jsr166 sources (without -Xmodule!) and we don't have a recommendation for how best to generate jsr166 docs in the jigsaw world. 04-08-2016 My mistake, I missed the link to the original email thread when going through outstanding issues. That counts as the use case I was looking for. 22-12-2015 We'd like to be able to build jsr166 CVS as a jigsaw module, or as part of one, so we can produce a jar file and html for docs, but javadoc does not like the violation of module boundaries. We're still looking for advice as to what jsr166 should do. $ ant -v -Djdk9.home="$HOME/jdk/jigsaw" -Djdk9.src.dir="$HOME/jdk/src/jigsaw" docs [javadoc] jsr166/pristine/src/main/java/util/concurrent/ConcurrentSkipListMap.java:2606: error: Node is not public in ConcurrentSkipListMap; cannot be accessed from outside package [javadoc] boolean isBeforeEnd(ConcurrentSkipListMap.Node<K,V> n, 22-12-2015 Need a compelling use case first. javac -Xmodule is about injecting extra classes into a module for the benefit of building patches for use with -Xpatch at runtime. It's not clear there is a compelling use case for the same feature at javadoc time. 22-12-2015