On Fri, 29 Oct 2021 10:12:25 GMT, Daniel Fuchs <dfu...@openjdk.org> wrote:
>> I still think it is too much of a corner case to impose on the API doc so >> much. How about changing the @throws to >> >> >> * @throws IllegalArgumentException if realm is an empty string or is >> not correctly >> * escaped, as specified in <a >> href="https://tools.ietf.org/html/rfc7230#section-3.2";> >> * RFC 7230 section-3.2</a>. >> ``` > > OK - but then I'd still say: `The value of the {@code realm} parameter will > be embedded in a quoted string.` > Otherwise the caller might think they need to provide a quoted string such > as: "\\"realm\\"" which would end up as realm=""realm"" over the wire, with > double double quotes. Or how about this? * @throws IllegalArgumentException if realm is an empty string or is not correctly * quoted, as specified in <a href="https://tools.ietf.org/html/rfc7230#section-3.2";> * RFC 7230 section-3.2</a>. Note, any {@code } character used for quoting must itself * also be quoted in source code. Would need to check the correct way to display a \ char. It possibly needs to be {@code \} for the same reason. ------------- PR: https://git.openjdk.java.net/jdk/pull/6117
