You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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.
--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.
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.
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:--doccopies the attribute verbatim (XmlDocFileWriter.WriteXmlDocFile), so<see cref="Parse"/>reaches the.xmlfile asParse. 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.Describe the solution you'd like
The same as C#, built on the XML doc ranges from #20637:
crefagainst the file's final environment (so it can point forward, as in C#): the enclosing type's members first, then values, types and modules — thenameofresolution order. A resolved cref is reported as a related symbol use of a new kind (RelatedSymbolUseKind.XmlDocCref), opt-in likeXmlDocParameterin Report XML doc parameter names as related symbol uses #20637, so symbol search is not bloated.--docwrites the documentation ID of the resolved symbol; an unresolved cref is written as!:Textand reported under FS3390. A cref that already carries a prefix (T:,M:, …) is kept as is.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
XmlDocSigOfValneeds the generalized type andValReprInfo, and the IDs are cached on theVal; they have to be made when--docwrites the file.Additional context
Questions before any code:
<param>names out of it..xmloutput a compiler change that can go in behind--doc, or does it need a language suggestion first?Related: #20630, #20637, #20638, #15134, #20591.