some gleanings from attempts to clean up Javadocs per Java 8 default lint checking

[Marshall Schor <ms...@schor.com>]

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.
&lt;, 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

Re: some gleanings from attempts to clean up Javadocs per Java 8 default lint checking

[Marshall Schor <ms...@schor.com>]

Re:

The JCas classes also cause another kind of warning in my Eclipse when custom type inherits form another custom type: Unnecessary @SuppressWarnings ("hiding") 

I think I need to see an example of where this happens - can you post one?

It seems to me that custom types should also exhibit this behavior, unless they're missing a field in their definition.

-Marshall

Re: some gleanings from attempts to clean up Javadocs per Java 8 default lint checking

[Marshall Schor <ms...@schor.com>]

On 12/11/2013 5:04 PM, Richard Eckart de Castilho wrote:
> On 11.12.2013, at 19:34, Marshall Schor <ms...@schor.com> wrote:
>
>> 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).
> Did you try just removing the @param and @return declarations for those obvious cases?

yes, the lint says they're missing if they're removed.
>
>> 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 */
> The JCas classes also cause another kind of warning in my Eclipse when custom type inherits form another custom type: Unnecessary @SuppressWarnings ("hiding") 
ok - maybe that can also be fixed...
>
>> 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…
> Are you considering to switch to real Java annotations (probably with RetentionPolicy.SOURCE)?
not at this time - it's more work :-)
And, I'm hoping to do another release right around the end of the year, to pick
up changes that some are waiting for.

-Marshall
>
> -- Richard

Re: some gleanings from attempts to clean up Javadocs per Java 8 default lint checking

[Richard Eckart de Castilho <re...@apache.org>]

On 11.12.2013, at 19:34, Marshall Schor <ms...@schor.com> wrote:

> 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).

Did you try just removing the @param and @return declarations for those obvious cases?

> 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 */

The JCas classes also cause another kind of warning in my Eclipse when custom type inherits form another custom type: Unnecessary @SuppressWarnings ("hiding") 

> 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…

Are you considering to switch to real Java annotations (probably with RetentionPolicy.SOURCE)?

-- Richard