On Mon, 22 Jun 2026 14:45:43 GMT, Nizar Benalla <[email protected]> wrote:
>> Please review this patch to support markdown link syntax in `@see`tags. >> >> --------- >> - [x] I confirm that I make this contribution in accordance with the >> [OpenJDK Interim AI Policy](https://openjdk.org/legal/ai). > > Nizar Benalla has updated the pull request incrementally with one additional > commit since the last revision: > > Add examples to comment The change looks good, but the handling of see tag contents in `SeeTaglet` requires some changes. As @liach said it would be nice to add comments on when these cases occur. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SeeTaglet.java line 175: > 173: // @see [label](url) > 174: if (ref.size() != 1 || !(ref.getFirst() instanceof > RawTextTree raw)) { > 175: return htmlWriter.commentTagsToContent(element, ref, > false, false); `ref.size() != 1` allows a Markdown text followed by other doctrees, such as: ``` /// @see [foo](bar) {@code something}``` I think the condition should trigger `invalidSeeTagOutput` instead. `!(ref.getFirst() instanceof RawTextTree)` should never be true as `ref.getFirst().getKind()` returned `MARKDOWN`, but if it was it would also indicate invalid input. src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/taglets/SeeTaglet.java line 179: > 177: String source = raw.getContent().strip(); > 178: if (!source.startsWith("[")) { > 179: return htmlWriter.commentTagsToContent(element, ref, > false, false); The only other form of the `@see` that creates a Markdown tree is the 2nd `<a href="url">label</a>` form. I think the condition could be written as `source.startsWith("<")`. ------------- Changes requested by hannesw (Reviewer). PR Review: https://git.openjdk.org/jdk/pull/31532#pullrequestreview-4561969487 PR Review Comment: https://git.openjdk.org/jdk/pull/31532#discussion_r3466913728 PR Review Comment: https://git.openjdk.org/jdk/pull/31532#discussion_r3467035662
