Skip to content

Resolve <see cref> in XML doc comments like C# #20640

Description

@xperiandri

Is your feature request related to a problem? Please describe.

<see cref="…"/>, <seealso cref>, <exception cref> and <permission cref> in F# /// comments are plain text to the compiler and the IDE:

  • --doc copies the attribute verbatim (XmlDocFileWriter.WriteXmlDocFile), so <see cref="Parse"/> reaches the .xml file as Parse. C# writes the documentation ID (M:Ns.Parser.Parse(System.String)), and tools that read the file (DocFX, fsdocs, Visual Studio tooltips of the consuming project) resolve IDs, not source names. The unresolved-cref diagnostic already exists (xmlDocUnresolvedCrossReference, FS3390 group) but is never raised.
  • In the editor, a cref is not a symbol: Go To Definition does nothing on it, renaming the type or member leaves it stale, and the tooltip prints the raw text.

Describe the solution you'd like

The same as C#, built on the XML doc ranges from #20637:

  1. The checker resolves each cref against the file's final environment (so it can point forward, as in C#): the enclosing type's members first, then values, types and modules — the nameof resolution order. A resolved cref is reported as a related symbol use of a new kind (RelatedSymbolUseKind.XmlDocCref), opt-in like XmlDocParameter in Report XML doc parameter names as related symbol uses #20637, so symbol search is not bloated.
  2. --doc writes the documentation ID of the resolved symbol; an unresolved cref is written as !:Text and reported under FS3390. A cref that already carries a prefix (T:, M:, …) is kept as is.
  3. The editor: Rename rewrites the last segment of the cref (Rename a parameter together with its XML doc param tags #20638 already passes all related kinds to Rename), Go To Definition works on it, and the tooltip shows the resolved name.

A first cut would cover types, modules, union cases, fields, properties, events and non-overloaded methods, and leave M(int) overload syntax, List{T} generics and operators for later.

Describe alternatives you've considered

  • Resolving where each doc comment is converted: a type's doc is converted before the rest of its recursive group and its members exist, so forward references would not resolve.
  • Producing the IDs during checking: XmlDocSigOfVal needs the generalized type and ValReprInfo, and the IDs are cached on the Val; they have to be made when --doc writes the file.

Additional context

Questions before any code:

  1. Should Find All References list crefs? C# does; Report XML doc parameter names as related symbol uses #20637/Rename a parameter together with its XML doc param tags #20638 keep <param> names out of it.
  2. Is rewriting the .xml output a compiler change that can go in behind --doc, or does it need a language suggestion first?
  3. Should FS3390 for an unresolved cref stay opt-in, like the rest of that warning?

Related: #20630, #20637, #20638, #15134, #20591.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions