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

[Martin Buchholz]

On Thu, Sep 26, 2013 at 5:45 PM, Jonathan Gibbons <
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));
    }