Clean up Javadoc

[nik9000]

We're disabling doclint in #13689 so the javadocs that we have will compile. We should get the javadocs to the point where they pass doclint - or at least pass some checks. We're not really sure what standards we should have for Javadoc but right now we don't have any.

[rmuir]

FWIW this is what lucene uses right now:

  <property name="javadoc.doclint.args" value="-Xdoclint:all -Xdoclint:-missing"/>
  <property name="javac.doclint.args" value="-Xdoclint:all/protected -Xdoclint:-missing"/>

Available options are: accessibility, html, missing, reference, or syntax

Maybe we should at least start with html, reference, syntax and fix the errors in docs we already have.

accessibility and missing require adding more (e.g. captions for images/tables, and javadocs for methods that don't currently have any).

And the other trick is to pass doclint options to javac too, meaning the compile will just fail (its a fast check) and you don't need to run any additional build target. See the example, for that to work, you have to specify the access level that you normally generate javadocs for (e.g. protected).

[nik9000]

Maybe we should at least start with html, reference, syntax and fix the errors in docs we already have.

And the other trick is to pass doclint options to javac too, meaning the compile will just fail (its a fast check) and you don't need to run any additional build target. See the example, for that to work, you have to specify the access level that you normally generate javadocs for (e.g. protected).

I think this is the right way to start on this. I suspect there are plenty of Javadoc errors to fix just with those options.

[rmuir]

I suspect there are plenty of Javadoc errors to fix just with those options.

That is the understatement of the year.