diff --git a/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs b/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs index 49a3419fb..4f4ad3ad9 100644 --- a/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs +++ b/src/FSharp.Formatting.ApiDocs/GenerateHtml.fs @@ -1,3 +1,5 @@ +/// Internal module that generates HTML documentation output from an . +/// Produces one HTML file per namespace and per entity, plus an index file. module internal FSharp.Formatting.ApiDocs.GenerateHtml open System @@ -13,6 +15,8 @@ open FSharp.Formatting.HtmlModel.Html /// Embed some HTML generated in GenerateModel let embed (x: ApiDocHtml) = !!x.HtmlText +/// Wraps the HTML text of an in a summary paragraph, +/// unless the content starts with a <pre> tag (which cannot be nested inside <p>). let fsdocsSummary (x: ApiDocHtml) = // the
 tag is not allowed inside a 

tag. if x.HtmlText.StartsWith("

", StringComparison.Ordinal) then
@@ -20,6 +24,9 @@ let fsdocsSummary (x: ApiDocHtml) =
     else
         div [ Class "fsdocs-summary-contents" ] [ p [ Class "fsdocs-summary" ] [ embed x ] ]
 
+/// Renders HTML API documentation for all namespaces and entities in an
+/// . Writes one file per namespace
+/// and per entity to the output directory using the supplied template.
 type HtmlRender(model: ApiDocModel, ?menuTemplateFolder: string) =
     let root = model.Root
     let collectionName = model.Collection.CollectionName
diff --git a/src/FSharp.Formatting.CodeFormat/Pervasive.fs b/src/FSharp.Formatting.CodeFormat/Pervasive.fs
index 14c649f77..9bb878ab1 100644
--- a/src/FSharp.Formatting.CodeFormat/Pervasive.fs
+++ b/src/FSharp.Formatting.CodeFormat/Pervasive.fs
@@ -11,6 +11,8 @@ open FSharp.Compiler.Text
 []
 do ()
 
+/// Computation expression builder for Async<'T option> workflows,
+/// enabling monadic short-circuiting on None.
 []
 type AsyncMaybeBuilder() =
 
@@ -93,6 +95,7 @@ type AsyncMaybeBuilder() =
 
 let asyncMaybe = AsyncMaybeBuilder()
 
+/// Lifts an Async<'T> into Async<'T option> by wrapping the result in Some.
 let inline liftAsync (computation: Async<'T>) : Async<'T option> =
     async {
         let! a = computation
@@ -100,9 +103,11 @@ let inline liftAsync (computation: Async<'T>) : Async<'T option> =
     }
 
 
+/// Additional async combinators used internally in the code-format pipeline.
 []
 module Async =
 
+    /// Maps a function over the result of an async workflow.
     let map (f: 'T -> 'U) (a: Async<'T>) : Async<'U> =
         async {
             let! a = a
diff --git a/src/FSharp.Formatting.Literate/ParsePynb.fs b/src/FSharp.Formatting.Literate/ParsePynb.fs
index c89a622e7..918e9f8b6 100644
--- a/src/FSharp.Formatting.Literate/ParsePynb.fs
+++ b/src/FSharp.Formatting.Literate/ParsePynb.fs
@@ -5,8 +5,11 @@ open System.Text.Json
 open FSharp.Formatting.Templating
 open FSharp.Formatting.PynbModel
 
+/// Internal module for parsing Jupyter notebook (.ipynb) files into  values
+/// that can be converted to Markdown or .fsx for literate processing.
 module internal ParsePynb =
 
+    /// A single cell from a Jupyter notebook, either a Markdown cell or a code cell.
     type ParsedCell =
         | Code of
             {| lang: string
@@ -39,7 +42,9 @@ module internal ParsePynb =
                     sprintf $"%s{codeBlock}\n(**\n%s{outputsString}\n*)"
             | Code _ -> $"(**\n%s{this.ToMarkdown()}\n*)"
 
+    /// Active patterns for matching Jupyter output cells by MIME type and output type.
     module Output =
+        /// Matches a JSON element that contains text/html output data.
         let (|TextHtml|_|) (x: JsonElement) =
             match x.TryGetProperty("text/html") with
             | true, html ->
@@ -51,6 +56,7 @@ module internal ParsePynb =
                 Some $"

%s{html}

" | _ -> None + /// Matches a JSON element that contains text/plain output data. let (|TextPlain|_|) (x: JsonElement) = match x.TryGetProperty("text/plain") with | true, text -> @@ -58,6 +64,7 @@ module internal ParsePynb = Some $"""
%s{text}
""" | _ -> None + /// Matches a display-data output cell and returns its rendered HTML or plain-text content. let (|DisplayData|_|) (x: JsonElement) = match x.TryGetProperty("output_type") with | true, outputType -> @@ -72,6 +79,7 @@ module internal ParsePynb = None | _ -> failwith "no output_type property" + /// Matches a stream output cell and returns its text content as an HTML code block. let (|Stream|_|) (x: JsonElement) = match x.TryGetProperty("output_type") with | true, outputType -> @@ -87,12 +95,14 @@ module internal ParsePynb = None | _ -> failwith "no output_type property" + /// Parses an output JSON element and returns its rendered HTML string. let parse (output: JsonElement) = match output with | Stream stream -> stream | DisplayData displayData -> displayData | s -> failwith $"""unknown output %s{s.GetProperty("output_type").GetString()}""" + /// Returns the concatenated source lines of a notebook cell as a single string. let getSource (cell: JsonElement) = let source = match cell.TryGetProperty("source") with @@ -101,6 +111,7 @@ module internal ParsePynb = source |> Seq.map (fun x -> x.GetString()) |> String.concat "" + /// Returns the rendered output strings from a code cell, or None if there are no outputs. let collectOutputs (cell: JsonElement) = match cell.TryGetProperty("outputs") with | true, outputs -> @@ -112,6 +123,7 @@ module internal ParsePynb = xs |> Seq.map Output.parse |> Seq.toArray |> Some | _ -> None + /// Parses a polyglot code cell, extracting the kernel name, source, and rendered outputs. let getCode (cell: JsonElement) = let lang = let metadata (elem: JsonElement) = @@ -140,6 +152,7 @@ module internal ParsePynb = outputs = outputs |} + /// Parses a single notebook cell JSON element into a . let parseCell (cell: JsonElement) = let cell_type = match cell.TryGetProperty("cell_type") with @@ -154,6 +167,7 @@ module internal ParsePynb = | "code" -> getCode cell | _ -> failwith $"unknown cell type %s{cell_type}" + /// Converts a Jupyter notebook JSON string to a Markdown string by serialising each cell. let pynbStringToMarkdown (ipynb: string) = let json = JsonDocument.Parse(ipynb) @@ -161,10 +175,12 @@ module internal ParsePynb = |> Seq.map (parseCell >> (fun x -> x.ToMarkdown())) |> String.concat "\n" + /// Reads a Jupyter notebook file and converts it to a Markdown string. let pynbToMarkdown ipynbFile = ipynbFile |> File.ReadAllText |> pynbStringToMarkdown + /// Converts a Jupyter notebook JSON string to an .fsx script string. let pynbStringToFsx (ipynb: string) = let json = JsonDocument.Parse(ipynb) @@ -172,9 +188,11 @@ module internal ParsePynb = |> Seq.map (parseCell >> (fun x -> x.ToFsx())) |> String.concat "\n" + /// Reads a Jupyter notebook file and converts it to an .fsx script string. let pynbToFsx ipynbFile = ipynbFile |> File.ReadAllText |> pynbStringToFsx + /// Reads the front-matter block from a Jupyter notebook file, if present in the first Markdown cell. let parseFrontMatter ipynbFile = let json = JsonDocument.Parse(ipynbFile |> File.ReadAllText)