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

[Jonathan Gibbons]

On 09/26/2013 06:00 PM, Martin Buchholz wrote:
>
>
>
> On Thu, Sep 26, 2013 at 5:45 PM, Jonathan Gibbons 
> <jonathan.gibbons at oracle.com <mailto:jonathan.gibbons at oracle.com>> wrote:
>
>     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?
>
>
> I really meant  "BUT we don't want javadoc, when run against private 
> methods, to enforce the same high standards as for public methods"
>
> E.g. for maintainers, adding @param or @returns (or @SuppressWarnings) 
> to the method below is not an improvement.
>
>     /**
>      * Returns the trigger time of a delayed action.
>      */
>     private long triggerTime(long delay, TimeUnit unit) {
>         return triggerTime(unit.toNanos((delay < 0) ? 0 : delay));
>     }
>

Martin,

OK, yes, that is more what I was expecting you meant. We ran across 
exactly the same situation when applying doclint to our own code.

If you invoke doclint from javac, you should have the flexibility you 
are looking for in the -Xdoclint option and its suboptions. You can set 
a high standard for public and protected methods, and a lower standard 
(or no standard) for private and package-private methods.

-- Jon