Cannot create clickable link rustdoc above match complex_value

[loynoir]

Code

Problem

• Cannot create clickable link rustdoc above match complex_value

pub fn actual() {
    ...

    // FIXME: not clickable link
    // see [`foo::bar::method`] complex value pattern matching
    match complex_value {
        ...
    }

    ...
}

Reproduction Steps

Expected Outcome

Workaroud by

• create clickable link rustdoc above match complex_value using _struct

pub fn workaround() {
    ...

    /// see [`foo::bar::method`] complex value pattern matching
    struct _HELP;
    match complex_value {
        ...
    }

    ...
}

Actual Output

Version

rustdoc 1.90.0-nightly (f8e355c 2025-07-27)

Additional Details

https://blog.rust-lang.org/2020/11/19/Rust-1.48/#easier-linking-in-rustdoc

[fmease]

rustdoc is a tool for documenting the API of a crate which consists of a tree of items (like functions, types (incl. their fields and so on)). rustdoc will never be a tool to document implementation details like the body of a function.

That's the reason why doc comments on non-items like match expressions/statements lead to an unused_doc_comment lint warning.

[fmease]

I do certainly see the wish/need for "semantic comments", i.e., a hypothetical kind of comment that isn't a doc comment but that hosts constructs (like "intra-doc" links and other kinds of hyperlink) that are checked by the compiler or downstream tools, so the comment less likely gets out of date.

However, this is T-lang RFC territory. I would recommend you to write up a pre-RFC for https://internals.rust-lang.org/ or https://rust-lang.zulipchat.com/ and go from there.

[fmease]

Since this is clearly out of scope for rustdoc, I'll close this issue in favor a potential T-lang RFC. Thanks for your understanding!