[Repo Assist] Add /// doc comments to XmlDocReader.fs and GenerateMarkdown.fs (issue #1035) (#1079)

* Add `///` doc comments to XmlDocReader.fs and GenerateMarkdown.fs (issue #1035)

Add XML documentation comments to all public-facing and module-level
functions in XmlDocReader.fs and GenerateMarkdown.fs, which had very
sparse coverage (2 and 9 triple-slash comments respectively).

XmlDocReader.fs: removeSpaces, readMarkdownCommentAsHtml, findCommand,
readXmlElementAsHtml, SummaryWithoutChildren, readXmlCommentAsHtmlAux,
combineHtml, combineHtmlOptions, combineComments, combineNamespaceDocs,
readXmlCommentAsHtml, readNamespaceDocs.

GenerateMarkdown.fs: htmlStringSafe, embed, embedSafe, br, sourceLink,
renderMembers, renderEntities, entityContent, namespaceContent,
listOfNamespacesAux, listOfNamespaces, Generate.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* ci: trigger checks

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Don Syme <dsyme@users.noreply.github.com>

Author: 3 people

src/FSharp.Formatting.ApiDocs/GenerateMarkdown.fs

@@ -19,11 +19,17 @@ let urlEncode (x: string) = HttpUtility.UrlEncode x
 /// Returns the trimmed HTML text of an <see cref="T:FSharp.Formatting.ApiDocs.ApiDocHtml"/> value.
 let htmlString (x: ApiDocHtml) = (x.HtmlText.Trim())
 
+/// Returns the trimmed HTML text of an <see cref="T:FSharp.Formatting.ApiDocs.ApiDocHtml"/> value,
+/// with newlines replaced by <c>&lt;br /&gt;</c> and pipe characters escaped for Markdown tables.
 let htmlStringSafe (x: ApiDocHtml) =
     (x.HtmlText.Trim()).Replace("\n", "<br />").Replace("|", "&#124;")
 
+/// Wraps an <see cref="T:FSharp.Formatting.ApiDocs.ApiDocHtml"/> value as a Markdown DSL node.
 let embed (x: ApiDocHtml) = !!(htmlString x)
+/// Wraps an <see cref="T:FSharp.Formatting.ApiDocs.ApiDocHtml"/> value as a Markdown DSL node,
+/// escaping characters that would break Markdown table cells.
 let embedSafe (x: ApiDocHtml) = !!(htmlStringSafe x)
+/// A Markdown DSL node representing an HTML line break.
 let br = !!"<br />"
 
 /// Renders Markdown API documentation for all namespaces and entities in an
@@ -34,11 +40,13 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) =
     let collectionName = model.Collection.CollectionName
     let qualify = model.Qualify
 
+    /// Renders a source-code link icon for a member or entity, returning an empty list when no URL is available.
     let sourceLink url =
         [ match url with
           | None -> ()
           | Some href -> link [ img "Link to source code" (sprintf "%scontent/img/github.png" root) ] (href) ]
 
+    /// Renders a Markdown section for a group of API members with the given section header.
     let renderMembers header (members: ApiDocMember list) =
         [ if members.Length > 0 then
               ``###`` [ !!header ]
@@ -123,6 +131,7 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) =
                   if not sl.IsEmpty then
                       p sl ]
 
+    /// Renders a Markdown table listing the given entities (types and modules) with links and summaries.
     let renderEntities (entities: ApiDocEntity list) =
         [ if entities.Length > 0 then
               let hasTypes = entities |> List.exists (fun e -> e.IsTypeDefinition)
@@ -160,6 +169,8 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) =
                           [ p [ embedSafe e.Comment.Summary ] ]
                           [ p [ yield! (sourceLink e.SourceLocation) ] ] ] ] ]
 
+    /// Generates the full Markdown content for a single entity (type or module) page,
+    /// including its summary, members grouped by category, and nested entities.
     let entityContent (info: ApiDocEntityInfo) =
         // Get all the members & comment for the type
         let entity = info.Entity
@@ -319,6 +330,8 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) =
                   yield! renderMembers "Instance members" instMembers
                   yield! renderMembers "Static members" statMembers ]
 
+    /// Generates the full Markdown content for a namespace page, including a table of contents
+    /// and one section per category of entities.
     let namespaceContent (nsIndex, ns: ApiDocNamespace) =
         let allByCategory = Categorise.entities (nsIndex, ns, false)
 
@@ -347,6 +360,8 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) =
 
                   yield! renderEntities category.CategoryEntites ]
 
+    /// Builds the list-of-namespaces Markdown fragment (for sidebar navigation or index page).
+    /// When <paramref name="nav"/> is <c>true</c> the active namespace is expanded to show its entities.
     let listOfNamespacesAux otherDocs nav (nsOpt: ApiDocNamespace option) =
         [
           // For FSharp.Core we make all entries available to other docs else there's not a lot else to show.
@@ -395,6 +410,7 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) =
                                                     (e.Url(root, collectionName, qualify, model.FileExtensions.InUrl)) ] ] ]
                       | _ -> () ]
 
+    /// Returns the list-of-namespaces string, using a menu template when available.
     let listOfNamespaces otherDocs nav (nsOpt: ApiDocNamespace option) =
         let noTemplatingFallback () =
             listOfNamespacesAux otherDocs nav nsOpt
@@ -442,6 +458,8 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) =
         let toc = listOfNamespaces true true None
         [ yield (ParamKeys.``fsdocs-list-of-namespaces``, toc) ]
 
+    /// Writes all API documentation Markdown files (index, one per namespace, one per entity)
+    /// to <paramref name="outDir"/>, applying <paramref name="templateOpt"/> to each page.
     member _.Generate(outDir: string, templateOpt, collectionName, globalParameters) =
 
         let getSubstitutons parameters toc (content: MarkdownDocument) pageTitle =

src/FSharp.Formatting.ApiDocs/XmlDocReader.fs

@@ -16,6 +16,8 @@ open FSharp.Patterns
 /// XML documentation comment reading and combining utilities.
 [<AutoOpen>]
 module internal XmlDocReader =
+    /// Normalises leading whitespace from a multi-line XML doc comment string, removing
+    /// the common indentation prefix that .NET compilers emit.
     let removeSpaces (comment: string) =
         use reader = new StringReader(comment)
 
@@ -28,6 +30,10 @@ module internal XmlDocReader =
 
         String.removeSpaces lines
 
+    /// Converts a Markdown-style literate document (used when a doc comment was written as
+    /// free Markdown text) into an <see cref="T:FSharp.Formatting.ApiDocs.ApiDocComment"/>.
+    /// Sections headed with <c>## Returns</c>, <c>## Examples</c>, <c>## Notes</c>, and
+    /// <c>## Remarks</c> are mapped to the corresponding ApiDocComment fields.
     let readMarkdownCommentAsHtml el (doc: LiterateDocument) =
         let groups = System.Collections.Generic.List<(_ * _)>()
 
@@ -107,6 +113,8 @@ module internal XmlDocReader =
             rawData = raw
         )
 
+    /// Tries to parse a <c>[key:value]</c> command embedded inside an XML doc text node.
+    /// Returns <c>Some (key, value)</c> on success or <c>None</c> if the text is not a command.
     let findCommand cmd =
         match cmd with
         | StringPosition.StartsWithWrapped ("[", "]") (ParseCommand(k, v), _rest) -> Some(k, v)
@@ -137,6 +145,11 @@ module internal XmlDocReader =
             else
                 $"<pre>%s{trimmed}</pre>"
 
+    /// Recursively converts an <see cref="T:System.Xml.Linq.XElement"/> to an HTML string,
+    /// resolving <c>&lt;see cref="…"/&gt;</c> references via <paramref name="urlMap"/> and
+    /// collecting any embedded <c>[key:value]</c> commands into <paramref name="cmds"/>.
+    /// When <paramref name="anyTagsOK"/> is <c>true</c>, unknown XML elements are passed
+    /// through as raw HTML; otherwise they are silently dropped.
     let rec readXmlElementAsHtml
         anyTagsOK
         (urlMap: CrossReferenceResolver)
@@ -217,12 +230,20 @@ module internal XmlDocReader =
                         let elemAsXml = elem.ToString()
                         html.Append(elemAsXml) |> ignore
 
+    /// Active pattern that matches a <c>&lt;summary&gt;</c> element that contains only text
+    /// (no child elements). Used to take a fast path that avoids the full HTML builder.
     let (|SummaryWithoutChildren|_|) (e: XElement) =
         if e.Name.LocalName = "summary" && not e.HasElements then
             Some e
         else
             None
 
+    /// Core function that processes a standard C#/F# XML documentation element (the root
+    /// <c>&lt;member …&gt;</c> or <c>&lt;doc&gt;</c> element) into an
+    /// <see cref="T:FSharp.Formatting.ApiDocs.ApiDocComment"/> plus an optional list of
+    /// <c>&lt;namespacedoc&gt;</c> sub-elements (for namespace-level summaries).
+    /// When <paramref name="summaryExpected"/> is <c>true</c>, a missing <c>&lt;summary&gt;</c>
+    /// child is treated as raw HTML content.
     let readXmlCommentAsHtmlAux
         summaryExpected
         (urlMap: CrossReferenceResolver)
@@ -409,15 +430,22 @@ module internal XmlDocReader =
 
         comment, nsels
 
+    /// Concatenates the HTML text of two <see cref="T:FSharp.Formatting.ApiDocs.ApiDocHtml"/> values,
+    /// separated by a newline.
     let combineHtml (h1: ApiDocHtml) (h2: ApiDocHtml) =
         ApiDocHtml(String.concat "\n" [ h1.HtmlText; h2.HtmlText ], None)
 
+    /// Combines two optional <see cref="T:FSharp.Formatting.ApiDocs.ApiDocHtml"/> values:
+    /// returns the non-<c>None</c> side, or concatenates both when both are present.
     let combineHtmlOptions (h1: ApiDocHtml option) (h2: ApiDocHtml option) =
         match h1, h2 with
         | x, None -> x
         | None, x -> x
         | Some x, Some y -> Some(combineHtml x y)
 
+    /// Merges two <see cref="T:FSharp.Formatting.ApiDocs.ApiDocComment"/> values by
+    /// concatenating their HTML sections (summary, remarks, parameters, examples, etc.).
+    /// Used when a symbol has documentation spread across multiple XML doc elements.
     let combineComments (c1: ApiDocComment) (c2: ApiDocComment) =
         ApiDocComment(
             xmldoc =
@@ -434,19 +462,28 @@ module internal XmlDocReader =
             rawData = c1.RawData @ c2.RawData
         )
 
+    /// Reduces a list of optional <see cref="T:FSharp.Formatting.ApiDocs.ApiDocComment"/> values
+    /// (namespace-level doc fragments) by combining all non-<c>None</c> entries into one.
+    /// Returns <c>None</c> when the list is empty or all entries are <c>None</c>.
     let combineNamespaceDocs nspDocs =
         nspDocs
         |> List.choose id
         |> function
             | [] -> None
             | xs -> Some(List.reduce combineComments xs)
 
+    /// Top-level XML doc reader: parses a <c>&lt;member&gt;</c> element (or similar) into an
+    /// <see cref="T:FSharp.Formatting.ApiDocs.ApiDocComment"/> and a separate namespace-doc
+    /// comment extracted from any embedded <c>&lt;namespacedoc&gt;</c> elements.
     let rec readXmlCommentAsHtml (urlMap: CrossReferenceResolver) (doc: XElement) (cmds: IDictionary<_, _>) =
         let doc, nsels = readXmlCommentAsHtmlAux true urlMap doc cmds
 
         let nsdocs = readNamespaceDocs urlMap nsels
         doc, nsdocs
 
+    /// Reads the contents of <c>&lt;namespacedoc&gt;</c> elements into a combined namespace
+    /// <see cref="T:FSharp.Formatting.ApiDocs.ApiDocComment"/>, or returns <c>None</c> when
+    /// the list is empty.
     and readNamespaceDocs (urlMap: CrossReferenceResolver) (nsels: XElement list option) =
         let nscmds = Dictionary() :> IDictionary<_, _>