From 3a91f6f6d91dd428ce341f445558cbf407c839d8 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 27 Feb 2026 10:51:18 +0000 Subject: [PATCH 1/2] Add /// doc comments to batch 3 modules (#1035) Add XML doc and /// comments to 4 files with minimal documentation: - ToolTipReader.fs: module-level doc, linesFromTaggedText - FsxFormatting.fs: module-level doc, formatAsFsx - MarkdownUtils.fs: module-level doc, isCode, isCodeOutput, getExecutionCount, getCode, getCodeOutput, splitParagraphs, adjustFsxCodeForConditionalDefines, applySubstitutionsInText, applyCodeReferenceResolver, applyDirectLinkResolver, mapText, mapInlineCode, mapDirectLink, mapSpans, mapParagraphs, applySubstitutionsInMarkdown - Formatting.fs: module-level doc, transformDocument Part of the ongoing effort tracked in #1035. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../ToolTipReader.fs | 6 +++++ src/FSharp.Formatting.Literate/Formatting.fs | 8 +++++++ .../FsxFormatting.fs | 4 ++++ .../MarkdownUtils.fs | 23 +++++++++++++++++++ 4 files changed, 41 insertions(+) diff --git a/src/FSharp.Formatting.CodeFormat/ToolTipReader.fs b/src/FSharp.Formatting.CodeFormat/ToolTipReader.fs index b0826ea76..404af490c 100644 --- a/src/FSharp.Formatting.CodeFormat/ToolTipReader.fs +++ b/src/FSharp.Formatting.CodeFormat/ToolTipReader.fs @@ -2,6 +2,10 @@ // F# CodeFormat (ToolTipReader.fs) // (c) Tomas Petricek, 2012, Available under Apache 2.0 license. // -------------------------------------------------------------------------------------- + +/// Internal module that reads FSharp.Compiler.Service tool-tip data and converts it +/// into the representation +/// used for rendering hover documentation in code snippets. module internal FSharp.Formatting.CodeFormat.ToolTipReader open System.Text @@ -14,6 +18,8 @@ open FSharp.Compiler.Text // Implements formatting of tool tips // -------------------------------------------------------------------------------------- +/// Converts an array of values emitted by +/// the F# compiler into a sequence of plain strings, splitting on newline-tagged spaces. let linesFromTaggedText (tags: TaggedText array) = seq { let content = StringBuilder() diff --git a/src/FSharp.Formatting.Literate/Formatting.fs b/src/FSharp.Formatting.Literate/Formatting.fs index 9c0c0824b..48c300a49 100644 --- a/src/FSharp.Formatting.Literate/Formatting.fs +++ b/src/FSharp.Formatting.Literate/Formatting.fs @@ -8,6 +8,9 @@ open FSharp.Formatting.CodeFormat open FSharp.Formatting.Markdown open FSharp.Formatting.Templating +/// Internal module that converts a into a +/// formatted output string (HTML, Latex, Markdown, .fsx, or .ipynb) and computes the +/// substitution key–value pairs used by the templating engine to populate page templates. module internal Formatting = /// Format document with the specified output kind @@ -111,6 +114,11 @@ module internal Formatting = yield line ] |> String.concat "\n" + /// Formats a literate document and produces the full set of template substitutions for the output page. + /// Extracts YAML front-matter metadata (title, category, index, description, keywords), builds + /// previous/next navigation links from , formats the document + /// body, and returns a record ready for + /// template rendering. let transformDocument // This array was sorted in BuildCommand.fs (filesWithFrontMatter: FrontMatterFile array) diff --git a/src/FSharp.Formatting.Markdown/FsxFormatting.fs b/src/FSharp.Formatting.Markdown/FsxFormatting.fs index 86195707a..351cab413 100644 --- a/src/FSharp.Formatting.Markdown/FsxFormatting.fs +++ b/src/FSharp.Formatting.Markdown/FsxFormatting.fs @@ -2,6 +2,8 @@ // Format a document as a .fsx // -------------------------------------------------------------------------------------- +/// Internal module for rendering a parsed Markdown/Literate AST back to an F# Script (.fsx) file. +/// Code blocks become plain F# code; prose blocks are wrapped in (** ... *) comments. module internal FSharp.Formatting.Markdown.FsxFormatting open MarkdownUtils @@ -72,6 +74,8 @@ let rec formatParagraphs ctx paragraphs = let cells = cell :: others cells +/// Formats a full literate document as an F# Script string. +/// Code cells become raw F# code; Markdown prose cells are wrapped in (** ... *) comment blocks. let formatAsFsx links substitutions newline crefResolver mdlinkResolver paragraphs = let ctx = { Links = links diff --git a/src/FSharp.Formatting.Markdown/MarkdownUtils.fs b/src/FSharp.Formatting.Markdown/MarkdownUtils.fs index 4eef947ec..5d7a2ed20 100644 --- a/src/FSharp.Formatting.Markdown/MarkdownUtils.fs +++ b/src/FSharp.Formatting.Markdown/MarkdownUtils.fs @@ -10,35 +10,45 @@ open System.Linq open System.Xml.Linq open FSharp.Formatting.Templating +/// Internal utilities shared across all Markdown formatting back-ends (HTML, Latex, Markdown, .fsx, .ipynb). +/// Provides helpers for inspecting and transforming the +/// AST, applying template substitutions, and resolving cross-references. module internal MarkdownUtils = + /// Returns true when the paragraph is a code block or inline HTML block. let isCode = (function | CodeBlock _ | InlineHtmlBlock _ -> true | _ -> false) + /// Returns true when the paragraph is an output block (e.g. a notebook cell output). let isCodeOutput = (function | OutputBlock _ -> true | _ -> false) + /// Extracts the optional execution count from a code or inline-HTML block; returns None for other paragraphs. let getExecutionCount = (function | CodeBlock(executionCount = executionCount) | InlineHtmlBlock(executionCount = executionCount) -> executionCount | _ -> None) + /// Extracts the source-code string from a code or inline-HTML block; raises if called on other paragraphs. let getCode = (function | CodeBlock(code = code) -> code | InlineHtmlBlock(code = code) -> code | _ -> failwith "unreachable") + /// Extracts the output text and MIME kind from an output block; raises if called on other paragraphs. let getCodeOutput = (function | OutputBlock(code, kind, _) -> code, kind | _ -> failwith "unreachable") + /// Splits a paragraph list at the first code block, returning the leading code (or prose) section + /// paired with the remaining paragraphs. Used by back-ends that process documents cell-by-cell. let splitParagraphs paragraphs = let firstCode = paragraphs |> List.tryFindIndex isCode @@ -239,6 +249,8 @@ module internal MarkdownUtils = printfn "// can't yet format %0A to markdown" paragraph yield "" ] + /// Strips #if SYMBOL / #endif // SYMBOL conditional compilation lines from an .fsx code block + /// so that format-specific sections are removed from non-target output formats. let adjustFsxCodeForConditionalDefines (defineSymbol, newLine) (code: string) = // Inside literate code blocks we conditionally remove some special lines to get nicer output for // load sections for different formats. We remove this: @@ -254,23 +266,30 @@ module internal MarkdownUtils = let code2 = String.concat newLine lines code2 + /// Applies template substitutions to a plain text string using the context's substitution table. let applySubstitutionsInText ctx (text: string) = SimpleTemplating.ApplySubstitutionsInText ctx.Substitutions text + /// Resolves a cref: inline-code span to a hyperlink if the reference is known; otherwise leaves it as inline code. let applyCodeReferenceResolver ctx (code, range) = match ctx.CodeReferenceResolver code with | None -> InlineCode(code, range) | Some(niceName, link) -> DirectLink([ Literal(niceName, range) ], link, None, range) + /// Resolves a direct link target through the context's Markdown link resolver, returning the mapped URL. let applyDirectLinkResolver ctx link = match ctx.MarkdownDirectLinkResolver link with | None -> link | Some newLink -> newLink + /// Extracts the text-transformation function from a triple of span-mapping functions. let mapText (f, _, _) text = f text + /// Extracts the inline-code transformation function from a triple of span-mapping functions. let mapInlineCode (_, f, _) (code, range) = f (code, range) + /// Applies the text function to the body and then the link function to the result. let mapDirectLink (fText, _, fLink) text = fLink (fText text) + /// Recursively maps a triple of transformation functions over all spans in a span list. let rec mapSpans fs (md: MarkdownSpans) = md |> List.map (function @@ -292,6 +311,8 @@ module internal MarkdownUtils = | LatexDisplayMath(code, range) -> LatexDisplayMath(code, range) | EmbedSpans(customSpans, range) -> EmbedSpans(customSpans, range)) + /// Recursively maps a triple of transformation functions over all paragraphs in a paragraph list, + /// including nested paragraphs inside list items, block-quotes, and tables. let rec mapParagraphs f (md: MarkdownParagraphs) = md |> List.map (function @@ -355,5 +376,7 @@ module internal MarkdownUtils = //let customParagraphsR = { new MarkdownEmbedParagraphs with member _.Render() = customParagraphs.Render() |> mapParagraphs f } EmbedParagraphs(customParagraphs, range)) + /// Applies all context substitutions (text replacements, cref resolution, and direct-link mapping) + /// to every span and paragraph in a Markdown document. let applySubstitutionsInMarkdown ctx md = mapParagraphs (applySubstitutionsInText ctx, applyCodeReferenceResolver ctx, applyDirectLinkResolver ctx) md From bd2cee706981f37ae1eeb1372c973f2edbae24a3 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Fri, 27 Feb 2026 10:54:11 +0000 Subject: [PATCH 2/2] ci: trigger CI checks