JDK-8176901 : Internal error running javadoc over jdk internal classes
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 9
  • Priority: P2
  • Status: Closed
  • Resolution: Fixed
  • Submitted: 2017-03-16
  • Updated: 2017-05-02
  • Resolved: 2017-04-04
The Version table provides details related to the release that this issue/RFE will be addressed.

Unresolved : Release in which this issue/RFE will be addressed.
Resolved: Release in which this issue/RFE has been resolved.
Fixed : Release in which this issue/RFE has been fixed. The release containing this fix may be available for download as an Early Access Release or a General Availability Release.

To download the current JDK release, click here.
JDK 10 JDK 9
10Fixed 9 b165Fixed
Related Reports
Duplicate :  
JDK-8177692 - NPE while building Apache Derby javadoc with b162 of jdk 9
Relates :  
JDK-8178014 - CryptoPolicyParser's API comment contains < and > characters
Description
There are known javadoc errors (e.g. mismatch between @param and parameter names) in core jdk non-public API.  An attempt to find all such (is there some better/blessed way?) via:

--- a/make/Javadoc.gmk
+++ b/make/Javadoc.gmk
@@ -186,7 +186,7 @@
     #
 
 DEFAULT_JAVADOC_OPTIONS := -XDignore.symbol.file=true -use -keywords -notimestamp \
-    -serialwarn -encoding ISO-8859-1 -breakiterator --system none
+    -serialwarn -encoding ISO-8859-1 -breakiterator --system none -package
 
 ################################################################################
 # Setup make rules for running javadoc.

provokes a javadoc internal error:

 $ rm -rf ./build/linux-x86_64-normal-server-release/images/docs/api; make docs-javadoc
...
Building target 'docs-javadoc' in configuration 'linux-x86_64-normal-server-release'
Generating Javadoc from 224 package(s) for api
javadoc: error - An internal exception has occurred. 
	(java.lang.NullPointerException)
Please file a bug against the javadoc tool via the Java bug reporting page
(http://bugreport.java.com) after checking the Bug Database (http://bugs.java.com)
for duplicates. Include error messages and the following diagnostic in your report. Thank you.
java.lang.NullPointerException
	at jdk.javadoc.internal.doclets.toolkit.util.JavaScriptScanner.visitAttribute(JavaScriptScanner.java:98)
	at jdk.javadoc.internal.doclets.toolkit.util.JavaScriptScanner.visitAttribute(JavaScriptScanner.java:46)
	at com.sun.tools.javac.tree.DCTree$DCAttribute.accept(DCTree.java:190)
	at com.sun.source.util.DocTreePathScanner.scan(DocTreePathScanner.java:71)
	at com.sun.source.util.DocTreeScanner.scan(DocTreeScanner.java:98)
	at com.sun.source.util.DocTreeScanner.visitStartElement(DocTreeScanner.java:437)
	at jdk.javadoc.internal.doclets.toolkit.util.JavaScriptScanner.visitStartElement(JavaScriptScanner.java:57)
	at jdk.javadoc.internal.doclets.toolkit.util.JavaScriptScanner.visitStartElement(JavaScriptScanner.java:46)
	at com.sun.tools.javac.tree.DCTree$DCStartElement.accept(DCTree.java:810)
	at com.sun.source.util.DocTreePathScanner.scan(DocTreePathScanner.java:71)
	at com.sun.source.util.DocTreeScanner.scanAndReduce(DocTreeScanner.java:83)
	at com.sun.source.util.DocTreeScanner.scan(DocTreeScanner.java:98)
	at com.sun.source.util.DocTreeScanner.scanAndReduce(DocTreeScanner.java:106)
	at com.sun.source.util.DocTreeScanner.visitDocComment(DocTreeScanner.java:184)
	at com.sun.tools.javac.tree.DCTree$DCDocComment.accept(DCTree.java:132)
	at com.sun.source.util.DocTreePathScanner.scan(DocTreePathScanner.java:50)
	at jdk.javadoc.internal.doclets.toolkit.util.JavaScriptScanner.scan(JavaScriptScanner.java:49)
	at jdk.javadoc.internal.doclets.toolkit.util.Utils.getDocCommentTree0(Utils.java:3037)
	at jdk.javadoc.internal.doclets.toolkit.util.Utils.getDocCommentTree(Utils.java:3088)
	at jdk.javadoc.internal.doclets.toolkit.util.Utils$WeakSoftHashMap.computeIfAbsent(Utils.java:3270)
	at jdk.javadoc.internal.doclets.toolkit.util.Utils.getCommentHelper(Utils.java:2878)
	at jdk.javadoc.internal.doclets.toolkit.util.Utils.hasBlockTag(Utils.java:2960)
	at jdk.javadoc.internal.doclets.toolkit.util.Utils.hasBlockTag(Utils.java:2956)
	at jdk.javadoc.internal.doclets.toolkit.util.Utils.isHidden(Utils.java:1556)
	at jdk.javadoc.internal.doclets.toolkit.util.ClassTree.buildTree(ClassTree.java:177)
	at jdk.javadoc.internal.doclets.toolkit.util.ClassTree.<init>(ClassTree.java:120)
	at jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:205)
	at jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.run(AbstractDoclet.java:117)
	at jdk.javadoc.doclet.StandardDoclet.run(StandardDoclet.java:68)
	at jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:608)
	at jdk.javadoc.internal.tool.Start.begin(Start.java:424)
	at jdk.javadoc.internal.tool.Start.begin(Start.java:341)
	at jdk.javadoc.internal.tool.Main.execute(Main.java:63)
	at jdk.javadoc.internal.tool.Main.main(Main.java:52)
1 error
Comments
I agree that a lot of TLC could be given to the private/package javadocs. While fixing JDK-8178014 without having the background of this bug, I noticed a lot of similar issues. This would should be a technical debt initiative.
02-05-2017
Fix Approved
04-04-2017
Fix Request Justification: this needs to be fixed since it is a NPE, it is difficult to zero-in on the root cause content, for the average user. It is a very low risk fix, simply a matter of adding a null check in the scanner logic
04-04-2017
The code is inconsistent since AttributeTree is defined to be able to return null, and the code in question does not check for null. /** * Returns the value of the attribute, or {@code null} if the kind is EMPTY. * @return the value of the attribute. */ List<? extends DocTree> getValue();
04-04-2017
Yes, we should fix the NPE, but it also looks like the codes in CryptoPolicyParser.java should be updated as well.
03-04-2017
The cause of this issue is http://hg.openjdk.java.net/jdk9/dev/jdk/file/6dea581453d7/src/java.base/share/classes/javax/crypto/CryptoPolicyParser.java#l49
03-04-2017
Similar issue having the same stack trace reported here https://bugs.openjdk.java.net/browse/JI-9048339 9 ea b162
28-03-2017
Kumar, Yes, thanks, I updated everything and running javadoc -Xdoclint:reference -Xmaxwarns 10000 -Xmaxerrs 10000 -package java/util/*.java now succeeds with jdk-9-ea+161
17-03-2017
The issue with the erasure was javadoc proceeding despite errors reported by javac, this was fixed with JDK-8175219, can you please check ?
17-03-2017
It seems that there is a rich vein of bugs to be found by running javadoc over the jdk sources. I suggest adding support to the makefiles for running javadoc with -package or -private; then fix all problems with the javadoc tool itself, and then at least some of the problems thus uncovered in the jdk sources - at least the sources should be clean with -Xdoclint:reference.
17-03-2017
I couldn't figure out any way to get warnings for non-public elements in jdk classes by tweaking DEFAULT_JAVADOC_OPTIONS, but that may just be because of the NPE in this bug. I also tried running javadoc by hand: jdk/src/java.base/share/classes $ javadoc -Xdoclint:reference -Xmaxwarns 10000 -Xmaxerrs 10000 -package java/util/*.java and that did report the desired: java/util/GregorianCalendar.java:733: error: @param name not found * @param aLocale the given locale BUT it also later crashed with a different NPE, which may or may not be a different bug: Generating ./java/util/package-tree.html... javadoc: error - An internal exception has occurred. (java.lang.NullPointerException) Please file a bug against the javadoc tool via the Java bug reporting page (http://bugreport.java.com) after checking the Bug Database (http://bugs.java.com) for duplicates. Include error messages and the following diagnostic in your report. Thank you. java.lang.NullPointerException at jdk.compiler/com.sun.tools.javac.code.Types.erasure(Types.java:2090) at jdk.compiler/com.sun.tools.javac.code.Types.access$800(Types.java:83) at jdk.compiler/com.sun.tools.javac.code.Types$14.visitTypeVar(Types.java:2148) at jdk.compiler/com.sun.tools.javac.code.Types$14.visitTypeVar(Types.java:2098) at jdk.compiler/com.sun.tools.javac.code.Type$TypeVar.accept(Type.java:1661) at jdk.compiler/com.sun.tools.javac.code.Types$DefaultTypeVisitor.visit(Types.java:4613) at jdk.compiler/com.sun.tools.javac.code.Types.erasure(Types.java:2093) at jdk.compiler/com.sun.tools.javac.code.Types.erasure(Types.java:2079) at jdk.compiler/com.sun.tools.javac.model.JavacTypes.erasure(JavacTypes.java:134) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.Utils$5.visitTypeVariable(Utils.java:1202) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.Utils$5.visitTypeVariable(Utils.java:1180) at jdk.compiler/com.sun.tools.javac.code.Type$TypeVar.accept(Type.java:1700) at java.compiler/javax.lang.model.util.AbstractTypeVisitor6.visit(AbstractTypeVisitor6.java:104) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.Utils.asTypeElement(Utils.java:1219) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.LinkInfoImpl.setContext(LinkInfoImpl.java:424) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.LinkInfoImpl.<init>(LinkInfoImpl.java:290) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.LinkFactoryImpl.getTypeParameterLink(LinkFactoryImpl.java:135) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.links.LinkFactory.getTypeParameterLinks(LinkFactory.java:277) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.util.links.LinkFactory.getLink(LinkFactory.java:195) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.HtmlDocletWriter.getLink(HtmlDocletWriter.java:1191) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.HtmlDocletWriter.addPreQualifiedClassLink(HtmlDocletWriter.java:1327) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.HtmlDocletWriter.addPreQualifiedStrongClassLink(HtmlDocletWriter.java:1340) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.AbstractTreeWriter.addPartialInfo(AbstractTreeWriter.java:185) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.AbstractTreeWriter.addLevelInfo(AbstractTreeWriter.java:92) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.AbstractTreeWriter.addLevelInfo(AbstractTreeWriter.java:94) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.AbstractTreeWriter.addTree(AbstractTreeWriter.java:129) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.AbstractTreeWriter.addTree(AbstractTreeWriter.java:112) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.PackageTreeWriter.generatePackageTreeFile(PackageTreeWriter.java:130) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.PackageTreeWriter.generate(PackageTreeWriter.java:107) at jdk.javadoc/jdk.javadoc.internal.doclets.formats.html.HtmlDoclet.generatePackageFiles(HtmlDoclet.java:340) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.startGeneration(AbstractDoclet.java:210) at jdk.javadoc/jdk.javadoc.internal.doclets.toolkit.AbstractDoclet.run(AbstractDoclet.java:117) at jdk.javadoc/jdk.javadoc.doclets.StandardDoclet.run(StandardDoclet.java:71) at jdk.javadoc/jdk.javadoc.internal.tool.Start.parseAndExecute(Start.java:608) at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:424) at jdk.javadoc/jdk.javadoc.internal.tool.Start.begin(Start.java:341) at jdk.javadoc/jdk.javadoc.internal.tool.Main.execute(Main.java:63) at jdk.javadoc/jdk.javadoc.internal.tool.Main.main(Main.java:52)
17-03-2017
I agree there is a woefully inadequate attention to detail on the doc comments for the internal API. The compilation options to help show the issues would be -Xdoclint:reference just check references to public or protected program elements (@param, @retuns, @throws, @see, {@link} etc) append one of /package or /private to include checks on package-private or private declarations -Xdoclint/package:<comma-separated-package-list>
16-03-2017
Thanks, but I couldn't figure out how to turn your comment into a concrete command line. The existence of /** * Constructs an empty GregorianCalendar. * * @param zone the given time zone * @param aLocale the given locale * @param flag the flag requesting an empty instance */ GregorianCalendar(TimeZone zone, Locale locale, boolean flag) { suggests that there has never been a serious effort to root out this class of errors in the jdk sources, despite the existence of the javadoc tool. Users might run into this when they run javadoc with -package on their own sources and the jdk sources on the sourcepath.
16-03-2017
The NPE is serious and must be fixed. But to address the initial question about bad parameter names, etc, I would suggest enabling doclint during compilation for reference checking (only) on desired packages at all desired access levels.
16-03-2017