On Thu, 5 Mar 2026 11:14:10 GMT, James Nord <[email protected]> wrote:
> The [existing > documentation](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/net/URL.html#constructor-deprecation) > when rendered was hard to read as the entire string was in a `pre` and > rendered in the same font. Coupled with the fact the the first URL would > contain a space this made it hard to scan as you had no visual clues and had > to backtrack to re-read what the sentence was trying to say. > > Switch to using inline definition using {@code} and swapped the order so that > the string without spaces came first negating any need for back tracking when > scanning @jtnord, thanks so much for the contribution. While I agree with your sentiment that we can improve readability of this class' JavaDoc, I think we can do better. I had an internal talk with @dfuch, and we agreed that the following further enhancements can be carried out: - Replace all `<blockquote><pre>[javadoc-newline][whitespace]http://...` with `<pre>{@code[javadoc-newline]http://...` - Use a consistent style in referrals to RFCs: `RFC 2396`-vs-`RFC2396` - [Types of URL] points to a very old external page which is very shallow in content. We can simply remove that referral. [Types of URL]: http://web.archive.org/web/20051219043731/http://archive.ncsa.uiuc.edu/SDG/Software/Mosaic/Demo/url-primer.html To give an idea, I share below the diff implementing above mentioned changes. @jtnord, unless you have objections, would you be open to integrating these enhancements to this PR? diff --git a/src/java.base/share/classes/java/net/URL.java b/src/java.base/share/classes/java/net/URL.java index 1e86f41fd3f..4704bca6a59 100644 --- a/src/java.base/share/classes/java/net/URL.java +++ b/src/java.base/share/classes/java/net/URL.java @@ -52,17 +52,13 @@ * Locator, a pointer to a "resource" on the World * Wide Web. A resource can be something as simple as a file or a * directory, or it can be a reference to a more complicated object, - * such as a query to a database or to a search engine. More - * information on the types of URLs and their formats can be found at: - * <a href= - * "http://web.archive.org/web/20051219043731/http://archive.ncsa.uiuc.edu/SDG/Software/Mosaic/Demo/url-primer.html";> - * <i>Types of URL</i></a> + * such as a query to a database or to a search engine. * <p> * In general, a URL can be broken into several parts. Consider the * following example: - * <blockquote><pre> - * http://www.example.com/docs/resource1.html - * </pre></blockquote> + * <pre>{@code + * http://www.example.com/docs/resource1.html + * }</pre> * <p> * The URL above indicates that the protocol to use is * {@code http} (HyperText Transfer Protocol) and that the @@ -80,9 +76,9 @@ * the protocol is used instead. For example, the default port for * {@code http} is {@code 80}. An alternative port could be * specified as: - * <blockquote><pre> - * http://www.example.com:1080/docs/resource1.html - * </pre></blockquote> + * <pre>{@code + * http://www.example.com:1080/docs/resource1.html + * }</pre> * <p> * The syntax of {@code URL} is defined by <a * href="http://www.ietf.org/rfc/rfc2396.txt";><i>RFC 2396: Uniform @@ -95,9 +91,9 @@ * A URL may have appended to it a "fragment", also known * as a "ref" or a "reference". The fragment is indicated by the sharp * sign character "#" followed by more characters. For example, - * <blockquote><pre> - * http://www.example.com/index.html#chapter1 - * </pre></blockquote> + * <pre>{@code + * http://www.example.com/index.html#chapter1 + * }</pre> * <p> * This fragment is not technically part of the URL. Rather, it * indicates that after the specified resource is retrieved, the @@ -109,17 +105,17 @@ * which contains only enough information to reach the resource * relative to another URL. Relative URLs are frequently used within * HTML pages. For example, if the contents of the URL: - * <blockquote><pre> - * http://www.example.com/index.html - * </pre></blockquote> + * <pre>{@code + * http://www.example.com/index.html + * }</pre> * contained within it the relative URL: - * <blockquote><pre> - * FAQ.html - * </pre></blockquote> + * <pre>{@code + * FAQ.html + * }</pre> * it would be a shorthand for: - * <blockquote><pre> - * http://www.example.com/FAQ.html - * </pre></blockquote> + * <pre>{@code + * http://www.example.com/FAQ.html + * }</pre> * <p> * The relative URL need not specify all the components of a URL. If * the protocol, host name, or port number is missing, the value is @@ -147,13 +143,16 @@ * syntax specification. * <p> * The URL class does not itself encode or decode any URL components - * according to the escaping mechanism defined in RFC2396. It is the + * according to the escaping mechanism defined in RFC 2396. It is the * responsibility of the caller to encode any fields, which need to be * escaped prior to calling URL, and also to decode any escaped fields, * that are returned from URL. Furthermore, because URL has no knowledge * of URL escaping, it does not recognise equivalence between the encoded - * or decoded form of the same URL. For example, the two URLs:<br> - * <pre> http://foo.com/hello world/ and http://foo.com/hello%20world</pre> + * or decoded form of the same URL. For example, the two URLs: + * <pre>{@code + * http://foo.com/hello world/ + * http://foo.com/hello%20world/ + * }</pre> * would be considered not equal to each other. * <p> * Note, the {@link java.net.URI} class does perform escaping of its @@ -164,7 +163,7 @@ * <p> * The {@link URLEncoder} and {@link URLDecoder} classes can also be * used, but only for HTML form encoding, which is not the same - * as the encoding scheme defined in RFC2396. + * as the encoding scheme defined in RFC 2396. * * @apiNote * @@ -190,7 +189,7 @@ * be abused to construct misleading URLs or URIs. Applications * that deal with URLs or URIs should take into account * the recommendations advised in <a - * href="https://tools.ietf.org/html/rfc3986#section-7";>RFC3986, + * href="https://tools.ietf.org/html/rfc3986#section-7";>RFC 3986, * Section 7, Security Considerations</a>. * <p> * All {@code URL} constructors may throw {@link MalformedURLException}. ------------- Changes requested by vyazici (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/30074#pullrequestreview-3924961835
