RFR: 8235786: Javadoc for com/sun/net/httpserver/HttpExchange.java#setAttribute is unclear

[Michael McMahon]

On Fri, 29 Nov 2024 09:13:31 GMT, Jaikiran Pai <jpai at openjdk.org> wrote:

> Can I please get a review of this doc-only change which proposes to clarify the behaviour of `com.sun.net.httpserver.HttpExchange.setAttribute()` and `com.sun.net.httpserver.HttpExchange.getAttribute()` methods?
> 
> As noted in https://bugs.openjdk.org/browse/JDK-8235786, it's not clear from the javadoc of these methods that the attributes that are set or retrieved through the exchange are actually those that belong to the entire `com.sun.net.httpserver.HttpContext` and thus are shared by all exchanges.
> 
> The commit in this PR specifies this behaviour to match the current implementation. I'll file a CSR once we settle on the text.

src/jdk.httpserver/share/classes/com/sun/net/httpserver/HttpExchange.java line 236:

> 234: 
> 235:     /**
> 236:      * {@return the attribute's value from this exchange's

It looks a bit odd in the generated doc that this statement appears as the summary and is then repeated verbatim in the @returns. Could the first sentence be a shorter summary?

Also, since we are clarifying the spec here, could a small test be added?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/22454#discussion_r1863450464