Automatic linking to reference entries

[alandefreitas]

Add automatic cross-referencing so that identifiers mentioned in prose (e.g. ReadStream, ReadStream(), Foo::bar) link to their Reference entry when one exists, without requiring an explicit @ref.

MrDocs already supports manual @ref. This request is for the implicit case Doxygen calls "automatic link generation."

Origin

Internal user feedback in the #mrdocs channel on cpplang Slack: https://cpplang.slack.com/archives/C0508A7LWUV/p1779136092575739

Paraphrased: documentation produced by MrDocs is otherwise great, but lacks links from prose back into the Reference. The user suggested two paths. Either stay with manual @ref everywhere, or detect inline code (e.g. `ReadStream`) and parenthesised names (e.g. ReadStream()) in prose, lists, and tables, and link them when the symbol exists.

The same comment proposes two follow-ups, which belong in a separate issue:

• Back-references from a Reference page to the prose sections that mention it.
• Auto-populating a See Also entry (and possibly a Description sentence) by extracting the surrounding sentence from the mention.

This issue is scoped to the core auto-link feature only.

How Doxygen does it

Reference: https://www.doxygen.nl/manual/autolink.html

Patterns that trigger an autolink in doxygen:

• URLs and email addresses are linked in HTML output.
• Class names: any word matching a documented class is linked, provided it contains at least one non-lowercase character. All-lowercase symbols are skipped to avoid false positives, and require explicit \ref.
• File names: any word containing a . that is not the last character is treated as a possible file name and linked if a documented file matches.
• Function references: seven patterns are recognised, including:
  • funcName(arg-list)
  • funcName()
  • ::funcName
  • ClassName::funcName, with optional argument list and const/volatile modifiers.
• For non-function members, ::name or ClassName::name are the recommended forms.
• For Javadoc compatibility, # is accepted in place of ::.

Disambiguation:

• If a function is overloaded and no argument list is given, Doxygen links to one of the overloads (non-deterministic).
• Scope can be omitted when the reference is to a member of the current class or an accessible base class.
• Function modifiers (const, volatile) are part of the match.

Opt-out:

• Prefix the word with % to suppress autolinking for that occurrence (e.g. %ReadStream).
• Explicit HTML <a href="..."> and \link ... \endlink win over an autolink.

Output-format notes:

• HTML: clickable links.
• LaTeX: page-number references instead of links.
• man pages: no link information generated.

Scope

Doxygen autolinks bare words in prose. That works for C++ identifiers that use CamelCase or snake_with_underscores, but produces false positives for common-English-looking lowercase names. Options we can provide for mrdocs enums:

• Never
• Only inside code spans (`Foo`). Lowest false-positive rate, but requires the author to mark up identifiers.
• Code spans plus name() / Class::member patterns in prose.
• Full prose-word matching with the non-lowercase rule. Most aggressive.

The scope of name lookup should be the same as @ref.

Confirm behavior inside tables, lists, blockquotes, footnotes, admonitions, headings, and inside @brief / @returns / parameter descriptions.