JDK-8210241 : bad javadoc comments in Java SE classes
  • Type: Bug
  • Component: tools
  • Sub-Component: javadoc(tool)
  • Affected Version: 9,10,11,12,13
  • Priority: P4
  • Status: Open
  • Resolution: Unresolved
  • Submitted: 2018-08-30
  • Updated: 2024-10-10
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.
Other
tbdUnresolved
Related Reports
Relates :  
JDK-8213817 - @return has already been specified (4 occurrences, in AWT and Swing)
Relates :  
JDK-8213820 - unknown tag: @returns
Relates :  
JDK-8213818 - @return has already been specified
Relates :  
JDK-8213819 - doclint should warn against {@index} inside tag
Description
This is a result of an email discussion on running javadoc on src.zip
http://mail.openjdk.java.net/pipermail/javadoc-dev/2018-August/000639.html

The bottom line is that running javadoc in the simple/obvious way (NOT just "make docs") results in 918 warnings, mostly caused by bad doc comments. The list is attached. 

java.base 254
java.compiler 1
java.datatransfer 1
java.desktop 189
java.instrument 1
java.logging 3
java.management 117
java.management.rmi 2
java.naming 25
java.net.http 7
java.prefs 1
java.rmi 19
java.scripting 2
java.se 2
java.security.jgss 20
java.security.sasl 3
java.sql 6
java.sql.rowset 31
java.transaction.xa 1
java.xml 303
java.xml.crypto 9

The bug is filed here as a placeholder;  we should create subtasks for various subsets of the modules, to render the work more manageable.
Comments
Analysing the list .... if we filter/sort the list, and remove all warnings about missing doc comments, the list boils down to error: malformed HTML error: reference not found error: unexpected end tag: </a> error: unknown tag: ByteBuffer error: unknown tag: extLink error: unknown tag: moduleGraph error: unknown tag: returns error: unknown tag: String warning: empty <P> tag warning: @return has already been specified Unexpected end tag is already known, {@index} is used inside <a>. There is a bug for the known instance of that; Also filed JDK-8213819 to update doclint. The malformed HTML is probably caused by generics in @link, which is being tracked separately; unknown tag ByteBuffer is the same; also unknown tag String Unknown tag extLink and moduleGraph are "not an issue" ... they need to be specified on the javadoc command line. Unknown tag: returns ... filed JDK-8213820 @return has already been specified: filed JDK-8213817, JDK-8213818 --- Updated Fix Version to 13, to update/review this task later.
13-11-2018
Agreed the errors for {@extLink} are false positives and would go away with a more complete command line. We don't have a good way of handling inline-tags without the taglet being present. We could make errors for @moduleGraph go away with an additional command line option. Supporting generics in links is JDK-8177280
30-08-2018
Some comments from looking over the list of messages: * The compile-time lint and doclint checks per module are configured in make/CompileJavaModules.gmk. The settings for a few notable modules are: java.base_ADD_JAVAC_FLAGS += -Xdoclint:all/protected,-reference '-Xdoclint/package:java.*,javax.*' -XDstringConcat=inline java.compiler_ADD_JAVAC_FLAGS += -Xdoclint:all/protected '-Xdoclint/package:java.*,javax.*' java.desktop_ADD_JAVAC_FLAGS += -Xdoclint:all/protected,-reference \ '-Xdoclint/package:java.*,javax.*' -Xlint:exports \ --doclint-format html4 The compile-time doclint checks therefore exclude private methods, which generally will exclude the serialization-related methods which are conventionally declared as private. * There are multiple errors reported for a case like extLink * {@extLink security_guide_xmldsig_rqmts DOM Mechanism Requirements} Arguably this is a config issue with how the check is being done since processing additional tags is fine (assuming they are processed as intended of course). Likewise, @moduleGraph is intentionally used. * There is long-standing lack of support for generics and @link, leading to cases like play/javadoc-demo/src/java.net.http/java/net/http/HttpResponse.java:698: error: malformed HTML * {@link Publisher Publisher<List<ByteBuffer>>} from which the body ^ play/javadoc-demo/src/java.net.http/java/net/http/HttpResponse.java:698: error: unknown tag: ByteBuffer * {@link Publisher Publisher<List<ByteBuffer>>} from which the body ^ play/javadoc-demo/src/java.net.http/java/net/http/HttpResponse.java:1163: error: unknown tag: String * a {@link Stream Stream<String>}, where each string in the stream * The java.xml module was not purged of doclint warnings. Warnings other than for serialization-related method and in cleaned-up areas that look legitimate include: play/javadoc-demo/src/java.net.http/java/net/http/HttpClient.java:107: error: unexpected end tag: </a> * <p> <a id="securitychecks"></a><b>Security checks</b></a> play/javadoc-demo/src/java.base/java/time/chrono/IsoChronology.java:673: warning: @return has already been specified * @return the ISO period, not null ^ This looks like a legitimate issue: * @param days the number of years, may be negative * @return the period in terms of this chronology, not null * @return the ISO period, not null */ play/javadoc-demo/src/java.desktop/javax/swing/text/CompositeView.java:722: warning: @return has already been specified * @return the next position west of the passed in position ^ play/javadoc-demo/src/java.desktop/javax/swing/text/LabelView.java:264: warning: @return has already been specified * @return the value of the cached ^ play/javadoc-demo/src/java.net.http/java/net/http/HttpClient.java:330: error: unexpected end tag: </a> * a set of system properties</a> related to ^ There are a few surprising inconsistencies in the checking being done in some cases, especially for duplicate tags. The javadoc issues should be fixed and the checks made consistent. I have some sympathy for documenting readObject methods and their kin, but it would be a nontrivial and tedious task.
30-08-2018
Note: the list is just for Java SE (java.*) modules. There may be more issues for JDK (jdk.*) modules.
30-08-2018