On Mon, 13 Apr 2026 15:22:41 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 > > James Nord has updated the pull request with a new target base due to a merge > or a rebase. The incremental webrev excludes the unrelated changes brought in > by the merge/rebase. The pull request contains three additional commits since > the last revision: > > - 8381184: incorporate feedback > - Merge remote-tracking branch 'origin/master' into patch-2 > - make the reading of URL encoding issues easier to read > > The existing documentation when rendered was hard to read for a 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 src/java.base/share/classes/java/net/URL.java line 60: > 58: * following example: > 59: * {@snippet lang="text" : > 60: * http://www.example.com/docs/resource1.html I suggest removing the trailing whitespace in **all** `@snippet` content. For instance, I've removed the trailing whitespace from this line, and re-built the docs. Contrast it with the `@snippet` I've not touched below: <img width="559" height="360" alt="Image" src="https://github.com/user-attachments/assets/551249ab-d410-4d41-87f3-790266ec0b07"; /> ------------- PR Review Comment: https://git.openjdk.org/jdk/pull/30074#discussion_r3078203621
