JDK-8090255 : Fix doclint errors and warnings in JavaFX API docs
  • Type: Bug
  • Component: javafx
  • Sub-Component: other
  • Affected Version: 8,9
  • Priority: P3
  • Status: Resolved
  • Resolution: Fixed
  • Submitted: 2014-08-15
  • Updated: 2021-07-01
  • Resolved: 2017-03-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.
JDK 9
9Fixed
Related Reports
Blocks :  
JDK-8163385 - Fix doclint errors and warnings in javafx.controls module
Blocks :  
JDK-8091730 - Enable -Xdoclint:all to treat all javadoc warnings as errors
Blocks :  
JDK-8163383 - Fix doclint errors and warnings in javafx.base module
Blocks :  
JDK-8163384 - Fix doclint errors and warnings in javafx.graphics module
Duplicate :  
JDK-8092662 - Identify and fix all broken JavaDoc links
Relates :  
JDK-8150130 - NPE building javafx docs with new doclet
Relates :  
JDK-8269774 - doclint reports missing javadoc comments for JavaFX properties if the docs are on the property method
Description
Many, many doclint warnings are reported by javadoc on various FX API documentation. We need to fix them, since they are almost always an indication of an actual problems with the docs. See RT-38330 for an example of a particularly bad problem that can arise from doclint warnings.
Comments
Changeset: 125b2c0a42a6 Author: kcr Date: 2017-03-10 09:06 -0800 URL: http://hg.openjdk.java.net/openjfx/9-dev/rt/rev/125b2c0a42a6 8090255: Fix doclint errors and warnings in JavaFX API docs Reviewed-by: jgiles, ckyang, jjg
10-03-2017
+1
10-03-2017
+1
10-03-2017
Webrev for the javafx.fxml, javafx.media, and javafx.web modules: http://cr.openjdk.java.net/~kcr/8090255/webrev.00/
10-03-2017
Here are two additional command line options that might be helpful: javadoc -Xmaxerrs 10000 -Xmaxwarns 10000 ... This will increase the limit of warnings and errors so that you can see all of them.
06-03-2017
With modular JDK 9, step 4 needs an extra argument: 4. Run the following, fixing up errors that you find: javadoc @javadoc.options @build/modulesourcepath.args
13-02-2017
Here is some additional information to help decide how best to split this up, since we don't want one very large webrev for all publicly-documented JavaFX classes. Here is the breakdown of packages in each module: base: 10 packages (see previous comment for initial webrev) graphics: 18 packages controls: 4 packages fxml: 1 package media: 1 package swing: 1 package swt: 1 package web: 1 package There are two aspects to organizing this work: 1) Determining the right grouping and granularity for the split (we don't want to see fifteen small reviews or one huge review). The grouping should be by package rather than just a random collection of classes. Where possible, each package sent out for review should be complete, meaning that all classes in that package are included in the webrev and that they are all "doclint-clean" with no more errors or warnings when running them with '-Xdoclint:all'. There may be some dependencies that are difficult to resolve without fixing classes in other packages, but that can be minimized by doing base first, then graphics (starting with javafx.scene and javafx.stage), then controls, then everything else (probably in any order). Grouping complete packages will make it easier to review, and in some cases to find the correct reviewers: I will review all of it, but I would also like Jonathan to review the controls, Alexander Z to review swing, etc. It would be fine to review one or more packages from the same module at the same time, or even two or more smaller modules, as long as in this case, each package in each of the modules being reviewed together are complete. 2) We need a separate bug ID for each separate batch of files that will be pushed at the same time; this can either be done as a JBS sub-task of this Bug, or as a separate bug linked to this bug such that the new bug "Blocks" this bug. Here is how I recommend to proceed: 1. Generate the javadocs using: gradle -PBUILD_JAVADOC=true sdk 2. Make a copy of the javadoc.options file into the rt dir: cp build/tmp/javadoc/javadoc.options . 3. Edit the javadoc.options file to change "-Xdoclint:none" to "-Xdoclint:all" and to prune the list of files to just the package (or packages) that you want to work on. 4. Run the following, fixing up errors that you find: javadoc @javadoc.options Note that it will only give you a max of 100 warnings or errors.
20-07-2016
webrev for base model: http://cr.openjdk.java.net/~ekleyman/8090255-base/
29-06-2016
Preliminary webrev: http://cr.openjdk.java.net/~ekleyman/RT-8090255/
08-06-2016
I attached a partial patch where I fixed up 12 files, so that should give you an idea of the kind of changes that will be needed.
03-05-2016
To build FX javadocs you need to do this: $ gradle -PBUILD_JAVADOC=true sdk To run with doclint turned on: $ gradle -PBUILD_JAVADOC=true -PDOC_LINT=all sdk Incremental builds of just the docs can be done by just running the javadoc command as follows: $ javadoc @build/tmp/javadoc/javadoc.options You can edit the javadoc.options file to turn doclint on (-Xdoclint:all) or off (-Xdoclint:none), or to trim the list of files, etc.
03-05-2016
Bumping to P3 and targeting to 9. The fact that we aren't doclint clean is an ongoing issue that hides real errors. Also, our use of -Xdoclint:none is causing us to trip over a bug in the new doclet code. See JDK-8150130.
19-02-2016
Unfortunately we are out of time for 8u40.
13-11-2014
warnings.txt - fixes a few warnings
18-08-2014
I also filed RT-38332 to enable treating doclint warnings as errors once we are doclint clean.
15-08-2014