RFR: 8316734: URLEncoder should specify that replacement bytes will be used in case of coding error [v2]

[Darragh Clarke]

On Fri, 24 Nov 2023 06:42:49 GMT, Alan Bateman <alanb at openjdk.org> wrote:

>> Darragh Clarke has updated the pull request incrementally with two additional commits since the last revision:
>> 
>>  - cleanup
>>  - implemented feedback
>
> src/java.base/share/classes/java/net/URLEncoder.java line 209:
> 
>> 207:      * <p>
>> 208:      * If a character needs encoding but cannot be encoded, the
>> 209:      * {@linkplain CharsetEncoder##cae replacement bytes} will be used.
> 
> I think this text will appear in the "Note" section of the method description. We are adding normative text so I think would be better if the new text went into the first paragraph or introduce a new parameter before the "Note". We could replace the "Note" heading with `@apiNote` if you want to clean this up.
> 
> As regards the text,  I think it would be more correct to say that if the input string is malformed, or if the input cannot be mapped to a valid byte sequence in the given charset, then the erroneous input with be replaced with the charset's replacement value.

Thanks for the input Alan, I pushed a commit that makes use of `@apiNote` and changed the wording of the text. Let me know if there is anything else that could be improved

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

PR Review Comment: https://git.openjdk.org/jdk/pull/16709#discussion_r1406233847