Add /// doc comments to batch 2 modules (#1035)

Add XML doc comments to 5 key source files:
- PynbModel.fs: Jupyter notebook model types
- HtmlModel.fs: HTML element DSL types and Html builder module
- CrossReferenceResolver.fs: cref resolution logic
- GenerateMarkdown.fs: Markdown API doc renderer
- GenerateHtml.fs: HTML API doc renderer

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

Author: 2 people

src/FSharp.Formatting.ApiDocs/CrossReferenceResolver.fs

@@ -1,3 +1,6 @@
+/// Resolves XML documentation cross-references (cref attributes) to hyperlinks pointing either to
+/// internal API doc pages or to external documentation (fsharp.github.io, learn.microsoft.com).
+/// Also manages URL base-name registration for all FSharp entities so internal links remain stable.
 namespace rec FSharp.Formatting.ApiDocs
 
 open System
@@ -24,7 +27,9 @@ open FSharp.Patterns
 open FSharp.Compiler.Syntax
 
 [<AutoOpen>]
+/// Helpers for computing XML doc signature strings (the T:/M:/P:... identifiers) for FSharp symbols.
 module internal CrossReferences =
+    /// Returns the XML doc signature for a type entity (e.g. "T:FSharp.Formatting.ApiDocs.ApiDocModel").
     let getXmlDocSigForType (typ: FSharpEntity) =
         if not (String.IsNullOrWhiteSpace typ.XmlDocSig) then
             typ.XmlDocSig
@@ -34,11 +39,14 @@ module internal CrossReferences =
             with _ ->
                 ""
 
+    /// Returns the single-letter XML doc sig prefix for a member: "E" for events, "P" for properties, "M" for other members.
     let getMemberXmlDocsSigPrefix (memb: FSharpMemberOrFunctionOrValue) =
         if memb.IsEvent then "E"
         elif memb.IsProperty then "P"
         else "M"
 
+    /// Returns the XML doc signature for a member (e.g. "M:MyNs.MyType.MyMethod(System.String)").
+    /// Falls back to constructing one from the member's compiled name and type parameters when the compiler hasn't filled it in.
     let getXmlDocSigForMember (memb: FSharpMemberOrFunctionOrValue) =
         if not (String.IsNullOrWhiteSpace memb.XmlDocSig) then
             memb.XmlDocSig
@@ -122,11 +130,14 @@ module internal CrossReferences =
             | None -> ""
             | Some fullName -> sprintf "%s:%s.%s" (getMemberXmlDocsSigPrefix memb) fullName memberName
 
+/// The result of resolving a cross-reference: a hyperlink URL plus a display name, and whether the target is internal.
 type internal CrefReference =
     { IsInternal: bool
       ReferenceLink: string
       NiceName: string }
 
+/// Resolves cref XML doc cross-references to URLs for the documentation site.
+/// Entities must be registered via <c>RegisterEntity</c> before resolution so that internal links can be built.
 type internal CrossReferenceResolver(root, collectionName, qualify, extensions) =
     let toReplace =
         ([ ("Microsoft.", ""); (".", "-"); ("`", "-"); ("<", "_"); (">", "_"); (" ", "_"); ("#", "_") ]

src/FSharp.Formatting.ApiDocs/GenerateHtml.fs

@@ -1,3 +1,5 @@
+/// Generates HTML-format API documentation pages from an <c>ApiDocModel</c>.
+/// Produces one HTML file per entity and per namespace, suitable for embedding in an fsdocs template.
 module internal FSharp.Formatting.ApiDocs.GenerateHtml
 
 open System
@@ -10,16 +12,18 @@ open FSharp.Formatting.Templating
 open FSharp.Formatting.HtmlModel
 open FSharp.Formatting.HtmlModel.Html
 
-/// Embed some HTML generated in GenerateModel
+/// Wraps pre-rendered API doc HTML as a raw <c>HtmlElement</c> text node.
 let embed (x: ApiDocHtml) = !!x.HtmlText
 
+/// Wraps an <c>ApiDocHtml</c> summary in a styled paragraph, unless it already starts with a <pre> block.
 let fsdocsSummary (x: ApiDocHtml) =
     // the <pre> tag is not allowed inside a <p> tag.
     if x.HtmlText.StartsWith("<pre>", StringComparison.Ordinal) then
         embed x
     else
         div [ Class "fsdocs-summary-contents" ] [ p [ Class "fsdocs-summary" ] [ embed x ] ]
 
+/// Renders API documentation pages in HTML format from the given <c>ApiDocModel</c>.
 type HtmlRender(model: ApiDocModel, ?menuTemplateFolder: string) =
     let root = model.Root
     let collectionName = model.Collection.CollectionName
@@ -694,6 +698,7 @@ type HtmlRender(model: ApiDocModel, ?menuTemplateFolder: string) =
 
         [ yield (ParamKeys.``fsdocs-list-of-namespaces``, toc); yield ParamKeys.``fsdocs-body-class``, "api-docs" ]
 
+    /// Generates all HTML API doc pages into <paramref name="outDir"/>, applying the given template and global parameters.
     member _.Generate(outDir: string, templateOpt, collectionName, globalParameters) =
 
         let getSubstitutons parameters toc (content: HtmlElement) pageTitle =

src/FSharp.Formatting.ApiDocs/GenerateMarkdown.fs

@@ -1,3 +1,5 @@
+/// Generates Markdown-format API documentation pages from an <c>ApiDocModel</c>.
+/// Produces one Markdown file per entity and per namespace, suitable for rendering with a Markdown template.
 module internal FSharp.Formatting.ApiDocs.GenerateMarkdown
 
 open System
@@ -8,19 +10,26 @@ open FSharp.Formatting.Markdown
 open FSharp.Formatting.Markdown.Dsl
 open FSharp.Formatting.Templating
 
+/// HTML-encodes a string and also escapes pipe characters (for use inside Markdown table cells).
 let encode (x: string) =
     HttpUtility.HtmlEncode(x).Replace("|", "&#124;")
 
+/// URL-encodes a string for use inside Markdown links.
 let urlEncode (x: string) = HttpUtility.UrlEncode x
+/// Extracts the plain HTML text from an <c>ApiDocHtml</c> value (trimmed).
 let htmlString (x: ApiDocHtml) = (x.HtmlText.Trim())
 
+/// Like <c>htmlString</c> but also replaces newlines with <br /> and escapes pipe characters (safe for table cells).
 let htmlStringSafe (x: ApiDocHtml) =
     (x.HtmlText.Trim()).Replace("\n", "<br />").Replace("|", "&#124;")
 
+/// Wraps <c>ApiDocHtml</c> as an inline Markdown text node.
 let embed (x: ApiDocHtml) = !!(htmlString x)
+/// Like <c>embed</c> but uses the table-safe encoding.
 let embedSafe (x: ApiDocHtml) = !!(htmlStringSafe x)
 let br = !!"<br />"
 
+/// Renders API documentation pages in Markdown format from the given <c>ApiDocModel</c>.
 type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) =
     let root = model.Root
     let collectionName = model.Collection.CollectionName
@@ -393,6 +402,7 @@ type MarkdownRender(model: ApiDocModel, ?menuTemplateFolder: string) =
         let toc = listOfNamespaces true true None
         [ yield (ParamKeys.``fsdocs-list-of-namespaces``, toc) ]
 
+    /// Generates all Markdown API doc pages into <paramref name="outDir"/>, applying the given template and global parameters.
     member _.Generate(outDir: string, templateOpt, collectionName, globalParameters) =
 
         let getSubstitutons parameters toc (content: MarkdownDocument) pageTitle =

src/FSharp.Formatting.Common/HtmlModel.fs

@@ -1,6 +1,10 @@
+/// Internal DSL for building and rendering HTML element trees, used by the API docs and template rendering pipeline.
+/// Provides typed representations of HTML properties and elements, and a fluent builder API in the <c>Html</c> module.
 namespace FSharp.Formatting.HtmlModel
 
 
+/// A discriminated union of all standard HTML attribute/property types.
+/// Each case represents one HTML attribute and carries its typed value.
 type internal HtmlProperties =
     | DefaultChecked of bool
     | DefaultValue of string
@@ -298,6 +302,9 @@ type internal HtmlProperties =
         | Unselectable s -> sprintf "unselectable=\"%s\"" (if s then "true" else "false")
         | Custom(k, v) -> sprintf "%s=\"%s\"" k v
 
+/// A typed representation of an HTML element tree node.
+/// Each case corresponds to an HTML tag. Leaf nodes hold <c>HtmlProperties</c> (attributes); branch nodes also hold child elements.
+/// The <c>String</c> case represents a raw text node; <c>EncodeString</c> HTML-encodes the text before output.
 type internal HtmlElement =
     private
     | A of props: HtmlProperties list * children: HtmlElement list
@@ -605,6 +612,8 @@ type internal HtmlElement =
 
         helper 1 tag
 
+/// Builder functions for creating <c>HtmlElement</c> values, one per HTML tag.
+/// Import this module (<c>open FSharp.Formatting.HtmlModel.Html</c>) to build element trees with a concise DSL.
 module internal Html =
     let a (props: HtmlProperties list) (children: HtmlElement list) = HtmlElement.A(props, children)
     let abbr (props: HtmlProperties list) (children: HtmlElement list) = HtmlElement.Abbr(props, children)

src/FSharp.Formatting.Common/PynbModel.fs

@@ -1,12 +1,17 @@
+/// Internal model for generating Jupyter notebook (.ipynb) files from literate scripts and F# Interactive sessions.
+/// Types in this module mirror the JSON structure of the Jupyter nbformat 4 spec.
 module internal FSharp.Formatting.PynbModel
 
 open System.Web
 
+/// Escapes a string for use as a JSON string value (with surrounding quotes).
 let escapeAndQuote (txt: string) =
     HttpUtility.JavaScriptStringEncode(txt, true)
 
+/// Ensures a string ends with a newline character, as required by the nbformat source line convention.
 let addLineEnd (s: string) = if s.EndsWith '\n' then s else s + "\n"
 
+/// Represents the output data payload of a notebook cell execution result, keyed by MIME type.
 type OutputData =
     | OutputData of kind: string * lines: string array
 
@@ -20,6 +25,7 @@ type OutputData =
             kind
             (String.concat ",\n" (Array.map escapeAndQuote lines))
 
+/// Represents a single output produced by executing a notebook code cell.
 type Output =
     { data: OutputData
       execution_count: int option
@@ -42,6 +48,7 @@ type Output =
             this.metadata
             this.output_type
 
+/// Represents a single cell in a Jupyter notebook (code, markdown, or raw).
 type Cell =
     { cell_type: string
       execution_count: int option
@@ -91,6 +98,7 @@ type Cell =
              |> Array.map (addLineEnd >> escapeAndQuote)
              |> String.concat ",\n    ")
 
+/// Metadata describing the kernel (language runtime) used to execute the notebook.
 type Kernelspec =
     { display_name: string
       language: string
@@ -112,6 +120,7 @@ type Kernelspec =
             (escapeAndQuote this.language)
             (escapeAndQuote this.name)
 
+/// Metadata describing the programming language used in the notebook (for syntax highlighting and MIME types).
 type LanguageInfo =
     { file_extension: string
       mimetype: string
@@ -137,6 +146,7 @@ type LanguageInfo =
             (escapeAndQuote this.name)
             (escapeAndQuote this.pygments_lexer)
 
+/// Polyglot Notebooks kernel info, identifying the default kernel for the notebook.
 type DefaultKernelInfo =
     { defaultKernelName: string
       languageName: string
@@ -165,6 +175,7 @@ type DefaultKernelInfo =
             (escapeAndQuote this.languageName)
             (escapeAndQuote this.name)
 
+/// Top-level notebook metadata combining kernel spec, language info, and Polyglot Notebooks extension data.
 type Metadata =
     { kernelspec: Kernelspec
       language_info: LanguageInfo
@@ -186,6 +197,7 @@ type Metadata =
             this.language_info
             this.defaultKernelInfo
 
+/// The root Jupyter notebook document, containing all cells and metadata.
 type Notebook =
     { nbformat: int
       nbformat_minor: int
@@ -216,6 +228,7 @@ type Notebook =
 let internal splitLines (s: string) =
     s.Replace("\r\n", "\n").Split([| '\n' |])
 
+/// Creates a code cell with the given source lines, execution count, and outputs.
 let codeCell (lines: string array) executionCount outputs =
     let lines = lines |> Array.collect splitLines |> Array.map addLineEnd
 
@@ -228,11 +241,13 @@ let codeCell (lines: string array) executionCount outputs =
 
     cell
 
+/// Creates a raw (non-executed) cell with the given content string.
 let rawCell (s: string) =
     { Cell.Default with
         cell_type = "raw"
         source = splitLines s }
 
+/// Creates a markdown cell with the given source lines.
 let markdownCell (lines: string array) =
     let lines = lines |> Array.collect splitLines |> Array.map addLineEnd