The Javadocs that comes with version 8 has a lint checker that's turned on by
default.
I've been looking at upgrading the core uima Javadocs to fix issues identified
by this checker. Some things I've learned:
It's checking conformance to HTML 4 spec. This spec disallows things like
<br/> (self closing), and things like <p> ....
<ul> an un-ordered list inside a paragraph
</ul>
</p>
The <ul> causes an "automatic" close of the <p>, so the lint complains when it
finds the following </p>.
For public APIs having Javadoc comments, the @param, @return @throws elements
must correspond to the situation, and have a non-blank description. So, a
parameter "aCAS" needs to be written @param aCAS the CAS (or something similar).
Elements like > and < and -> etc, need to be written using xml entities. e.g.
<, etc.
The JCas generation mechanism currently produces things it uses to control its
weaving together of user-added code with generated code. These things are
Javadoc comments, for example:
/** @generated */
This will have to be carefully reworked, because the generated Javadoc comments
won't pass the lint test for various reasons. This may take a bit of work /
time...
Finally, I learned that for methods which have a type parameter, like <T>, that
parameter must be included in the Javadocs, like this: @param <T> ....
-Marshall
