Implement <inheritdoc> XML documentation support for F#

docs/release-notes/.FSharp.Compiler.Service/11.0.0.md

@@ -24,6 +24,7 @@
 * Debugger: provide breakpoint ranges for short lambdas ([#19067](https://github.com/dotnet/fsharp/pull/19067))
 * FSharpDiagnostic: add default severity ([#19152](https://github.com/dotnet/fsharp/pull/19152))
 * Add support for triple quoted ASCII byte string ([#19182](https://github.com/dotnet/fsharp/pull/19182))
+* Add `<inheritdoc>` XML documentation support, resolved at tooling time via FCS Symbols API. ([PR #19188](https://github.com/dotnet/fsharp/pull/19188))
 
 ### Changed
 

src/Compiler/Driver/XmlDocFileWriter.fs

@@ -78,11 +78,14 @@ module XmlDocWriter =
         doModuleSig None generatedCcu.Contents
 
     let WriteXmlDocFile (g, assemblyName, generatedCcu: CcuThunk, xmlFile) =
+
         if not (FileSystemUtils.checkSuffix xmlFile "xml") then
             error (Error(FSComp.SR.docfileNoXmlSuffix (), Range.rangeStartup))
 
         let mutable members = []
 
+        // <inheritdoc> elements are written to the XML file as-is.
+        // Resolution happens at tooling time (IDE tooltips, FCS Symbols API).
         let addMember id xmlDoc =
             if hasDoc xmlDoc then
                 let doc = xmlDoc.GetXmlText()

src/Compiler/Driver/XmlDocFileWriter.fsi

@@ -15,4 +15,5 @@ module XmlDocWriter =
 
     /// Writes the XmlDocSig property of each element (field, union case, etc)
     /// of the specified compilation unit to an XML document in a new text file.
+    /// <inheritdoc> elements are written to the XML file as-is; resolution happens at tooling time.
     val WriteXmlDocFile: g: TcGlobals * assemblyName: string * generatedCcu: CcuThunk * xmlFile: string -> unit

src/Compiler/FSComp.txt

@@ -1670,6 +1670,7 @@ forFormatInvalidForInterpolated4,"Interpolated strings used as type IFormattable
 3390,xmlDocDuplicateParameter,"This XML comment is invalid: multiple documentation entries for parameter '%s'"
 3390,xmlDocUnresolvedCrossReference,"This XML comment is invalid: unresolved cross-reference '%s'"
 3390,xmlDocMissingParameter,"This XML comment is incomplete: no documentation for parameter '%s'"
+3390,xmlDocInheritDocError,"This XML comment is invalid: inheritdoc error: %s"
 3391,tcImplicitConversionUsedForNonMethodArg,"This expression uses the implicit conversion '%s' to convert type '%s' to type '%s'. See https://aka.ms/fsharp-implicit-convs. This warning may be disabled using '#nowarn \"3391\"."
 3392,containerDeprecated,"The 'AssemblyKeyNameAttribute' has been deprecated. Use 'AssemblyKeyFileAttribute' instead."
 3393,containerSigningUnsupportedOnThisPlatform,"Key container signing is not supported on this platform."

src/Compiler/FSharp.Compiler.Service.fsproj

@@ -472,6 +472,10 @@
     <Compile Include="Driver\CompilerOptions.fs" />
     <Compile Include="Driver\OptimizeInputs.fsi" />
     <Compile Include="Driver\OptimizeInputs.fs" />
+    <Compile Include="Symbols\XmlDocSigParser.fsi" />
+    <Compile Include="Symbols\XmlDocSigParser.fs" />
+    <Compile Include="Symbols\XmlDocInheritance.fsi" />
+    <Compile Include="Symbols\XmlDocInheritance.fs" />
     <Compile Include="Driver\XmlDocFileWriter.fsi" />
     <Compile Include="Driver\XmlDocFileWriter.fs" />
     <Compile Include="Driver\BinaryResourceFormats.fsi" />

src/Compiler/Symbols/SymbolHelpers.fs

@@ -343,6 +343,8 @@ module internal SymbolHelpers =
     let GetXmlCommentForItemAux (xmlDoc: XmlDoc option) (infoReader: InfoReader) m d =
         match xmlDoc with
         | Some xmlDoc when not xmlDoc.IsEmpty  ->
+            // <inheritdoc> elements are left intact here. Full resolution happens through the
+            // Symbols.fs path (FSharpEntity.XmlDoc / FSharpMemberOrFunctionOrValue.XmlDoc).
             FSharpXmlDoc.FromXmlText xmlDoc
         | _ -> GetXmlDocHelpSigOfItemForLookup infoReader m d
 

src/Compiler/Symbols/XmlDocInheritance.fs

@@ -0,0 +1,161 @@
+// Copyright (c) Microsoft Corporation.  All Rights Reserved.  See License.txt in the project root for license information.
+
+module internal FSharp.Compiler.XmlDocInheritance
+
+open System.Xml.Linq
+open System.Xml.XPath
+open FSharp.Compiler.DiagnosticsLogger
+open FSharp.Compiler.Text
+
+/// Represents an inheritdoc directive found in XML documentation
+type InheritDocDirective =
+    {
+        /// Optional cref attribute specifying explicit target
+        Cref: string option
+        /// Optional path attribute for XPath filtering
+        Path: string option
+        /// The original XElement for replacement
+        Element: XElement
+    }
+
+/// Checks if an XML document contains <inheritdoc> elements
+let private hasInheritDoc (xmlText: string) = xmlText.IndexOf("<inheritdoc") >= 0
+
+/// Extracts inheritdoc directives from parsed XML
+let private extractInheritDocDirectives (doc: XDocument) =
+    let inheritDocName = XName.op_Implicit "inheritdoc" |> Operators.nonNull
+
+    let crefName = XName.op_Implicit "cref" |> Operators.nonNull
+    let pathName = XName.op_Implicit "path" |> Operators.nonNull
+
+    doc.Descendants(inheritDocName)
+    |> Seq.map (fun elem ->
+        let crefAttr = elem.Attribute(crefName)
+        let pathAttr = elem.Attribute(pathName)
+
+        {
+            Cref =
+                match crefAttr with
+                | null -> None
+                | attr -> Some attr.Value
+            Path =
+                match pathAttr with
+                | null -> None
+                | attr -> Some attr.Value
+            Element = elem
+        })
+    |> List.ofSeq
+
+/// Applies an XPath filter to XML content
+let private applyXPathFilter (m: range) (xpath: string) (sourceXml: string) : string option =
+    try
+        let doc =
+            XDocument.Parse("<doc>" + sourceXml + "</doc>", LoadOptions.PreserveWhitespace)
+
+        // If the xpath starts with /, it's an absolute path that won't work with our wrapper
+        // Adjust to search within the doc
+        let adjustedXpath =
+            if xpath.StartsWith("/") && not (xpath.StartsWith("//")) then
+                "/doc" + xpath
+            else
+                xpath
+
+        let selectedElements = doc.XPathSelectElements(adjustedXpath)
+
+        if Seq.isEmpty selectedElements then
+            None
+        else
+            let result =
+                selectedElements
+                |> Seq.map (fun elem -> elem.ToString(SaveOptions.DisableFormatting))
+                |> String.concat "\n"
+
+            Some result
+    with ex ->
+        warning (Error(FSComp.SR.xmlDocInheritDocError ($"invalid XPath '{xpath}': {ex.Message}"), m))
+        None
+
+/// Recursively expands inheritdoc in the retrieved documentation
+let rec private expandInheritedDoc
+    (resolveCref: string -> string option)
+    (implicitTargetCrefOpt: string option)
+    (m: range)
+    (visited: Set<string>)
+    (cref: string)
+    (xmlText: string)
+    : string =
+    if visited.Contains(cref) then
+        xmlText
+    else
+        let newVisited = visited.Add(cref)
+        expandInheritDocFromXmlText resolveCref implicitTargetCrefOpt m newVisited xmlText
+
+/// Expands `<inheritdoc>` elements in XML documentation text.
+/// The caller provides a `resolveCref` function that maps a cref string to its resolved XML doc text.
+/// Takes an optional implicit target cref for resolving <inheritdoc/> without cref attribute.
+/// Tracks visited signatures to prevent infinite recursion.
+/// Takes a pre-computed xmlText string, avoiding an extra GetXmlText() call.
+and expandInheritDocFromXmlText
+    (resolveCref: string -> string option)
+    (implicitTargetCrefOpt: string option)
+    (m: range)
+    (visited: Set<string>)
+    (xmlText: string)
+    : string =
+    if not (hasInheritDoc xmlText) then
+        xmlText
+    else
+        try
+            let wrappedXml = "<doc>\n" + xmlText + "\n</doc>"
+            let xdoc = XDocument.Parse(wrappedXml, LoadOptions.PreserveWhitespace)
+
+            let directives = extractInheritDocDirectives xdoc
+
+            if directives.IsEmpty then
+                xmlText
+            else
+                let resolveAndReplace (directive: InheritDocDirective) (cref: string) (implicitCrefForRecursion: string option) =
+                    if visited.Contains(cref) then
+                        warning (Error(FSComp.SR.xmlDocInheritDocError ($"Circular reference detected for '{cref}'"), m))
+                    else
+                        match resolveCref cref with
+                        | Some inheritedXml ->
+                            let expandedInheritedXml =
+                                expandInheritedDoc resolveCref implicitCrefForRecursion m visited cref inheritedXml
+
+                            let contentToInherit =
+                                match directive.Path with
+                                | Some xpath ->
+                                    applyXPathFilter m xpath expandedInheritedXml
+                                    |> Option.defaultValue expandedInheritedXml
+                                | None -> expandedInheritedXml
+
+                            try
+                                let newContent = XElement.Parse("<temp>" + contentToInherit + "</temp>")
+                                directive.Element.ReplaceWith(newContent.Nodes())
+                            with ex ->
+                                warning (Error(FSComp.SR.xmlDocInheritDocError ($"Failed to process inheritdoc: {ex.Message}"), m))
+                        | None -> warning (Error(FSComp.SR.xmlDocInheritDocError ($"Cannot resolve cref '{cref}'"), m))
+
+                for directive in directives do
+                    match directive.Cref with
+                    | Some cref -> resolveAndReplace directive cref implicitTargetCrefOpt
+                    | None ->
+                        match implicitTargetCrefOpt with
+                        | Some implicitCref -> resolveAndReplace directive implicitCref None
+                        | None ->
+                            warning (
+                                Error(
+                                    FSComp.SR.xmlDocInheritDocError ("Implicit inheritdoc (without cref) requires a base type or interface"),
+                                    m
+                                )
+                            )
+
+                match xdoc.Root with
+                | null -> xmlText
+                | root ->
+                    root.Nodes()
+                    |> Seq.map (fun node -> node.ToString(SaveOptions.DisableFormatting))
+                    |> String.concat "\n"
+        with :? System.Xml.XmlException ->
+            xmlText

src/Compiler/Symbols/XmlDocInheritance.fsi

@@ -0,0 +1,18 @@
+// Copyright (c) Microsoft Corporation.  All Rights Reserved.  See License.txt in the project root for license information.
+
+module internal FSharp.Compiler.XmlDocInheritance
+
+open FSharp.Compiler.Text
+
+/// Expands `<inheritdoc>` elements in XML documentation text.
+/// The caller provides a `resolveCref` function to look up documentation by cref string.
+/// Takes an optional implicit target cref for resolving <inheritdoc/> without cref attribute.
+/// Takes a set of visited signatures to prevent cycles.
+/// Takes a pre-computed xmlText string, avoiding an extra GetXmlText() call.
+val expandInheritDocFromXmlText:
+    resolveCref: (string -> string option) ->
+    implicitTargetCrefOpt: string option ->
+    m: range ->
+    visited: Set<string> ->
+    xmlText: string ->
+        string

src/Compiler/Symbols/XmlDocSigParser.fs

@@ -0,0 +1,89 @@
+// Copyright (c) Microsoft Corporation.  All Rights Reserved.  See License.txt in the project root for license information.
+
+namespace FSharp.Compiler.Symbols
+
+open System.Text.RegularExpressions
+
+/// Represents the kind of element in a documentation comment ID
+[<RequireQualifiedAccess>]
+type DocCommentIdKind =
+    | Type
+    | Method
+    | Property
+    | Field
+    | Event
+    | Namespace
+    | Unknown
+
+/// Represents a parsed documentation comment ID (cref format)
+[<RequireQualifiedAccess>]
+type ParsedDocCommentId =
+    /// Type reference (T:Namespace.Type)
+    | Type of path: string list
+    /// Member reference (M:, P:, E:) with type path, member name, generic arity, and kind
+    | Member of typePath: string list * memberName: string * genericArity: int * kind: DocCommentIdKind
+    /// Field reference (F:Namespace.Type.field)
+    | Field of typePath: string list * fieldName: string
+    /// Invalid or unparseable ID
+    | None
+
+module XmlDocSigParser =
+    // Hoisted to module level to avoid re-creating compiled Regex on every call
+    let private docCommentIdRx =
+        Regex(@"^(?<kind>\w):(?<entity>[\w\d#`.]+)(?<args>\(.+\))?(?:~([\w\d.]+))?$", RegexOptions.Compiled)
+
+    let private fnGenericArgsRx =
+        Regex(@"^(?<entity>.+)``(?<typars>\d+)$", RegexOptions.Compiled)
+
+    /// Parse a documentation comment ID string (e.g., "M:Namespace.Type.Method(System.String)")
+    let parseDocCommentId (docCommentId: string) =
+
+        let m = docCommentIdRx.Match(docCommentId)
+        let kindStr = m.Groups["kind"].Value
+
+        match m.Success, kindStr with
+        | true, ("M" | "P" | "E") ->
+            let parts = m.Groups["entity"].Value.Split('.')
+
+            if parts.Length < 2 then
+                ParsedDocCommentId.None
+            else
+                let entityPath = parts[.. (parts.Length - 2)] |> List.ofArray
+                let memberOrVal = parts[parts.Length - 1]
+
+                // Try and parse generic params count from the name
+                let genericM = fnGenericArgsRx.Match(memberOrVal)
+
+                let (memberOrVal, genericParametersCount) =
+                    if genericM.Success then
+                        (genericM.Groups["entity"].Value, int genericM.Groups["typars"].Value)
+                    else
+                        memberOrVal, 0
+
+                let kind =
+                    match kindStr with
+                    | "M" -> DocCommentIdKind.Method
+                    | "P" -> DocCommentIdKind.Property
+                    | "E" -> DocCommentIdKind.Event
+                    | _ -> DocCommentIdKind.Unknown
+
+                // Handle constructor name conversion (#ctor in doc comments, .ctor in F#)
+                let finalMemberName = if memberOrVal = "#ctor" then ".ctor" else memberOrVal
+
+                ParsedDocCommentId.Member(entityPath, finalMemberName, genericParametersCount, kind)
+
+        | true, "T" ->
+            let entityPath = m.Groups["entity"].Value.Split('.') |> List.ofArray
+            ParsedDocCommentId.Type entityPath
+
+        | true, "F" ->
+            let parts = m.Groups["entity"].Value.Split('.')
+
+            if parts.Length < 2 then
+                ParsedDocCommentId.None
+            else
+                let entityPath = parts[.. (parts.Length - 2)] |> List.ofArray
+                let memberOrVal = parts[parts.Length - 1]
+                ParsedDocCommentId.Field(entityPath, memberOrVal)
+
+        | _ -> ParsedDocCommentId.None

src/Compiler/Symbols/XmlDocSigParser.fsi

@@ -0,0 +1,30 @@
+// Copyright (c) Microsoft Corporation.  All Rights Reserved.  See License.txt in the project root for license information.
+
+namespace FSharp.Compiler.Symbols
+
+/// Represents the kind of element in a documentation comment ID
+[<RequireQualifiedAccess>]
+type DocCommentIdKind =
+    | Type
+    | Method
+    | Property
+    | Field
+    | Event
+    | Namespace
+    | Unknown
+
+/// Represents a parsed documentation comment ID (cref format)
+[<RequireQualifiedAccess>]
+type ParsedDocCommentId =
+    /// Type reference (T:Namespace.Type)
+    | Type of path: string list
+    /// Member reference (M:, P:, E:) with type path, member name, generic arity, and kind
+    | Member of typePath: string list * memberName: string * genericArity: int * kind: DocCommentIdKind
+    /// Field reference (F:Namespace.Type.field)
+    | Field of typePath: string list * fieldName: string
+    /// Invalid or unparseable ID
+    | None
+
+module XmlDocSigParser =
+    /// Parse a documentation comment ID string (e.g., "M:Namespace.Type.Method(System.String)")
+    val parseDocCommentId: docCommentId: string -> ParsedDocCommentId