RFR 8025173 : HashMap.put() replacing an existing key can trigger a resize()

[Jonathan Gibbons]

The new diagnostics are generated by the new doclint feature which is 
available from the javac and javadoc command lines.

When invoked from javadoc, it only checks the comments being used for 
the docs that you are generating. So, if you are generating docs for 
just your public and protected methods, doclint will not (or should not) 
warn about your package-private and private methods.  The decision of 
which doc comments to check comes from the standard javadoc command line 
options used to select the elements to document, i.e. -private, 
-package, -protected, -public.

When invoked from javac, you actually have somewhat more versatility. 
The -Xdoclint command line option for javac actually allows you to 
specify different access levels for different types of check, so you 
could check syntax errors for all comments but only check for missing 
comments on public and protected elements.

With respect to your specific comments, I wonder if there is a typo in 
your message, because it doesn't quite make sense as written:

> We would like to use javadoc style, and have the javadoc tool warn us 
> of "real bugs" in our javadoc (even private methods) BUT we don't want 
> javadoc to enforce the same high standards for public methods, e.g. 
> don't require all of the @param for type parameters.

The word "public" in "the same high standards for public methods" makes 
more sense to me if you meant "private" here.  Which did you really mean?

-- Jon


On 09/26/2013 05:16 PM, Martin Buchholz wrote:
> Yes, I see your problem.  It's one we have in jsr166 development as well.
>
> We would like to use javadoc style, and have the javadoc tool warn us 
> of "real bugs" in our javadoc (even private methods) BUT we don't want 
> javadoc to enforce the same high standards for public methods, e.g. 
> don't require all of the @param for type parameters.
>
> I think javadoc's current increased level of warning will have the 
> unintended consequence of causing users to revert to /* comments.
> I would disable the more controversial ones by default.
>
>
> On Thu, Sep 26, 2013 at 10:51 AM, Brent Christian 
> <brent.christian at oracle.com <mailto:brent.christian at oracle.com>> wrote:
>
>     On 9/25/13 4:03 PM, Martin Buchholz wrote:
>
>         Looks good.
>         I would only suggest the stylistic improvement of using proper /**
>         javadoc comments even for private test methods instead of /*
>
>
>     The comments were meant as internal documentation and not "real"
>     javadoc.  After dabbling with some doclint cleanup a while ago,
>     I'm inclined now to only use /** if what I'm writing will be
>     doclint-clean.  testItr(), for instance, would (at least) need
>     @param tags and that's more than I thought was needed for this
>     test code.
>
>     So that was the thinking there.
>
>     Thanks,
>     -Brent
>
>