RFR: 8324573: HashMap::putAll add notes for conservative resizing [v7]

[Joshua Cao]

On Fri, 5 Apr 2024 15:57:24 GMT, Volker Simonis <simonis at openjdk.org> wrote:

>> I tried looking at the docs with `make docs-image`, but I can't test that the syntax/links are actually correct because `@implNote` does not actually show up in the web pages. As I understand from [the original proposal](https://mail.openjdk.org/pipermail/lambda-libs-spec-experts/2013-January/001211.html), `@implNote` is there to help to developer understand implementation, and is not intended to be exposed in the web docs.
>> 
>> This seems like information that would be useful to the consumer. So maybe we can consider moving this into the main comment block?
>
>> I tried looking at the docs with `make docs-image`, but I can't test that the syntax/links are actually correct because `@implNote` does not actually show up in the web pages. As I understand from [the original proposal](https://mail.openjdk.org/pipermail/lambda-libs-spec-experts/2013-January/001211.html), `@implNote` is there to help to developer understand implementation, and is not intended to be exposed in the web docs.
>> 
>> This seems like information that would be useful to the consumer. So maybe we can consider moving this into the main comment block?
> 
> @caojoshua the `@implNote` should definitely appear in the public API documentation, if not something is wrong. See for example: https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/Collections.html#method-detail

@simonis it was not showing up because the `implNote` was attached to private `putMapEntries`. I moved the `implNote` to public `putAll()`. It makes more sense there since the comment actually just talks about `putAll()`.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/17544#issuecomment-2048561831