Merge branch 'main' into repo-assist/fix-issue-1022-split-buildcommand-7a7c06d9bd38078d

Author: dsyme

RELEASE_NOTES.md

@@ -8,6 +8,7 @@
 
 ### Added
 
+* Add `///` documentation comments to all public types, modules and members, and succinct internal comments, as part of ongoing effort to document the codebase. [#1035](https://github.com/fsprojects/FSharp.Formatting/issues/1035)
 * Add "Copy" button to all code blocks in generated documentation, making it easy to copy code samples to the clipboard. [#72](https://github.com/fsprojects/FSharp.Formatting/issues/72)
 * Add `<FsDocsAllowExecutableProject>true</FsDocsAllowExecutableProject>` project file setting to include executable projects (OutputType=Exe/WinExe) in API documentation generation. [#918](https://github.com/fsprojects/FSharp.Formatting/issues/918)
 * Add `{{fsdocs-logo-alt}}` substitution (configurable via `<FsDocsLogoAlt>` MSBuild property, defaults to `Logo`) for accessible alt text on the header logo image. [#626](https://github.com/fsprojects/FSharp.Formatting/issues/626)

src/FSharp.Formatting.ApiDocs/Categorise.fs

@@ -1,9 +1,10 @@
+/// Internal helpers for grouping API doc entities and members by their declared categories
 [<RequireQualifiedAccess>]
 module internal FSharp.Formatting.ApiDocs.Categorise
 
 open System
 
-// Honour the CategoryIndex to put the categories in the right order
+/// Returns entities/members sorted by CategoryIndex then category name, with excluded items removed
 let private getSortedCategories xs exclude category categoryIndex =
     xs
     |> List.filter (exclude >> not)
@@ -12,7 +13,7 @@ let private getSortedCategories xs exclude category categoryIndex =
     |> List.sortBy (fun (cat, _xs, x) -> categoryIndex x, cat)
     |> List.map (fun (cat, xs, _x) -> cat, xs)
 
-// Group all members by their category
+/// Groups members by their Category/CategoryIndex, sorts alphabetically within each category
 let getMembersByCategory (members: ApiDocMember list) =
     getSortedCategories members (fun m -> m.Exclude) (fun m -> m.Category) (fun m -> m.CategoryIndex)
     |> List.mapi (fun i (key, elems) ->
@@ -26,6 +27,7 @@ let getMembersByCategory (members: ApiDocMember list) =
 
         (i, elems, name))
 
+/// Returns the categorised, sorted, and (optionally) suppressed entity list for a namespace
 let entities (nsIndex: int, ns: ApiDocNamespace, suppress) =
     let entities = ns.Entities
 
@@ -105,6 +107,7 @@ let entities (nsIndex: int, ns: ApiDocNamespace, suppress) =
 
     allByCategory
 
+/// Returns the category groups for every namespace in the model, skipping empty namespaces
 let model (apiDocModel: ApiDocModel) =
     [ for (nsIndex, ns) in Seq.indexed apiDocModel.Collection.Namespaces do
           let allByCategory = entities (nsIndex, ns, true)

src/FSharp.Formatting.ApiDocs/GenerateSearchIndex.fs

@@ -1,18 +1,23 @@
+/// Internal module for building the JSON search index from an <see cref="ApiDocModel"/>
 module internal FSharp.Formatting.ApiDocs.GenerateSearchIndex
 
 open FSharp.Formatting.ApiDocs
 
+/// Bundles all entity and model data needed while building search entries
 type AssemblyEntities =
     { Entities: ApiDocEntity list
       GeneratorOutput: ApiDocModel }
 
 
+/// Recursively collects an entity and all its nested entities
 let rec collectEntities (m: ApiDocEntity) =
     [ yield m; yield! m.NestedEntities |> List.collect collectEntities ]
 
+/// The search index type tag used to identify API-docs entries
 [<Literal>]
 let ApiDocs = "apiDocs"
 
+/// Builds all search index entries for the given <see cref="ApiDocModel"/>
 let searchIndexEntriesForModel (model: ApiDocModel) =
     let allEntities =
         [ for n in model.Collection.Namespaces do
@@ -23,6 +28,7 @@ let searchIndexEntriesForModel (model: ApiDocModel) =
         { Entities = allEntities
           GeneratorOutput = model }
 
+    /// Builds a single search entry for a member under the given enclosing entity name
     let doMember enclName (memb: ApiDocMember) =
         let cnt =
             [ yield enclName + "." + memb.Name
@@ -41,7 +47,7 @@ let searchIndexEntriesForModel (model: ApiDocModel) =
 
     let refs =
         [| for nsp in model.Collection.Namespaces do
-               // the entry is found when searching for types and modules
+               // Namespace entry: content lists all child type/module names for search
                let ctn =
                    [ for e in nsp.Entities do
                          e.Name ]
@@ -53,7 +59,7 @@ let searchIndexEntriesForModel (model: ApiDocModel) =
                  ``type`` = ApiDocs
                  headings = List.empty }
 
-           // generate a search index entry for each entity in the assembly
+           // One entry per entity (type/module), plus one per member
            for e in entities.Entities do
                let cnt =
                    [ e.Name

src/FSharp.Formatting.CodeFormat/Constants.fs

@@ -1,76 +1,102 @@
+/// Internal CSS class name constants used when emitting syntax-highlighted HTML
 module internal FSharp.Formatting.CodeFormat.Constants
 
+/// CSS class name constants for syntax token categories
 [<RequireQualifiedAccessAttribute>]
 module CSS =
 
+    /// CSS class for comment tokens
     [<Literal>]
     let Comment = "c"
 
+    /// CSS class for default/plain tokens
     [<Literal>]
     let Default = ""
 
+    /// CSS class for identifier tokens
     [<Literal>]
     let Identifier = "id"
 
+    /// CSS class for inactive (excluded by conditional compilation) tokens
     [<Literal>]
     let Inactive = "inactive"
 
+    /// CSS class for keyword tokens
     [<Literal>]
     let Keyword = "k"
 
+    /// CSS class for numeric literal tokens
     [<Literal>]
     let Number = "n"
 
+    /// CSS class for operator tokens
     [<Literal>]
     let Operator = "o"
 
+    /// CSS class for preprocessor directive tokens
     [<Literal>]
     let Preprocessor = "pp"
 
+    /// CSS class for string literal tokens
     [<Literal>]
     let String = "s"
 
+    /// CSS class for module/namespace tokens
     [<Literal>]
     let Module = "m"
 
+    /// CSS class for reference type tokens
     [<Literal>]
     let ReferenceType = "rt"
 
+    /// CSS class for value type tokens
     [<Literal>]
     let ValueType = "vt"
 
+    /// CSS class for function tokens
     [<Literal>]
     let Function = "fn"
 
+    /// CSS class for pattern match tokens
     [<Literal>]
     let Pattern = "pat"
 
+    /// CSS class for mutable variable tokens
     [<Literal>]
     let MutableVar = "mv"
 
+    /// CSS class for printf format string tokens
     [<Literal>]
     let Printf = "pf"
 
+    /// CSS class for escaped character tokens
     [<Literal>]
     let Escaped = "esc"
 
+    /// CSS class for disposable tokens
     [<Literal>]
     let Disposable = "d"
 
+    /// CSS class for type argument tokens
     [<Literal>]
     let TypeArgument = "ta"
 
+    /// CSS class for punctuation tokens
     [<Literal>]
     let Punctuation = "pn"
 
+    /// CSS class for enumeration tokens
     [<Literal>]
     let Enumeration = "en"
 
+    /// CSS class for interface tokens
     [<Literal>]
     let Interface = "if"
 
+    /// CSS class for property tokens
     [<Literal>]
     let Property = "prop"
 
+    /// CSS class for union case tokens
     [<Literal>]
     let UnionCase = "uc"

src/FSharp.Formatting.Common/Log.fs

@@ -2,35 +2,48 @@ namespace FSharp.Formatting.Common
 
 open System.Diagnostics
 
+/// Internal logging helpers backed by a <see cref="System.Diagnostics.TraceSource"/>
 module internal Log =
+    /// The shared TraceSource used by all FSharp.Formatting logging
     let source = new System.Diagnostics.TraceSource "FSharp.Formatting"
 
+    /// Creates a TraceListener that writes to the console
     let ConsoleListener () =
         { new TraceListener() with
             override __.WriteLine(s: string) = System.Console.WriteLine(s)
             override __.Write(s: string) = System.Console.Write(s) }
 
+    /// Creates a TraceListener that writes to a file
     let TextListener (file: string) = new TextWriterTraceListener(file)
 
+    /// Clears existing listeners, sets the level to All, and attaches the given listeners to the source
     let SetupSource (listeners: _ array) (source: TraceSource) =
         source.Listeners.Clear()
         source.Switch.Level <- System.Diagnostics.SourceLevels.All
         source.Listeners.AddRange listeners
 
+    /// Configures a listener with the given trace output options and event level filter
     let SetupListener traceOptions levels (listener: TraceListener) =
         listener.Filter <- new EventTypeFilter(levels)
         listener.TraceOutputOptions <- traceOptions
         listener
 
+    /// Adds a listener to the given TraceSource
     let AddListener listener (source: TraceSource) = source.Listeners.Add listener |> ignore
 
+    /// Emits a trace event of the given type using printf-style formatting
     let traceEventf t f =
         Printf.kprintf (fun s -> source.TraceEvent(t, 0, s)) f
 
+    /// Logs an informational message
     let infof f =
         traceEventf TraceEventType.Information f
 
+    /// Logs an error message
     let errorf f = traceEventf TraceEventType.Error f
+    /// Logs a warning message
     let warnf f = traceEventf TraceEventType.Warning f
+    /// Logs a critical message
     let critf f = traceEventf TraceEventType.Critical f
+    /// Logs a verbose message
     let verbf f = traceEventf TraceEventType.Verbose f

src/FSharp.Formatting.Common/Menu.fs

@@ -1,17 +1,21 @@
+/// Internal helpers for building navigation menu HTML from template files
 module FSharp.Formatting.Common.Menu
 
 open System
 open System.IO
 open FSharp.Formatting.Templating
 
+/// A single navigation menu item with its link, display text, and active state
 type MenuItem =
     { Link: string
       Content: string
       IsActive: bool }
 
+/// Converts a display string to a snake_case HTML id attribute value
 let private snakeCase (v: string) =
     System.Text.RegularExpressions.Regex.Replace(v, "[A-Z]", "$0").Replace(" ", "_").ToLower()
 
+/// Renders an HTML navigation menu for the given header and items using template files in `input`
 let createMenu (input: string) (isCategoryActive: bool) (header: string) (items: MenuItem list) : string =
     let pwd = Directory.GetCurrentDirectory()
     let menuTemplate = File.ReadAllText(Path.Combine(pwd, input, "_menu_template.html"))
@@ -39,12 +43,14 @@ let createMenu (input: string) (isCategoryActive: bool) (header: string) (items:
            ParamKeys.``fsdocs-menu-items``, menuItems |]
         menuTemplate
 
+/// Returns true when both required menu template files exist in `input`
 let isTemplatingAvailable (input: string) : bool =
     let pwd = Directory.GetCurrentDirectory()
     let menuTemplate = Path.Combine(pwd, input, "_menu_template.html")
     let menuItemTemplate = Path.Combine(pwd, input, "_menu-item_template.html")
     File.Exists(menuTemplate) && File.Exists(menuItemTemplate)
 
+/// Returns the last-write timestamps of the two menu template files
 let getLastWriteTimes (input: string) : DateTime list =
     let pwd = Directory.GetCurrentDirectory()
 

src/FSharp.Formatting.Common/PageContentList.fs

@@ -1,12 +1,15 @@
-module FSharp.Formatting.Common.PageContentList
+/// Builds a "page content" table-of-contents menu by scanning heading links in rendered HTML
+module FSharp.Formatting.Common.PageContentList
 
 open System.Text.RegularExpressions
 open FSharp.Formatting.HtmlModel
 open FSharp.Formatting.HtmlModel.Html
 
+/// Placeholder HTML emitted when a page has no headings to list
 [<Literal>]
 let EmptyContent = "<div class=\"empty\"></div>"
 
+/// Parses the rendered HTML to extract heading links and builds a nested <ul> table-of-contents.
 /// We process the html to collect the table of content.
 /// We can't use the doc.MarkdownDocument because we cannot easily get the generated id values.
 /// It is safer to parse the html.

src/FSharp.Formatting.Common/Range.fs

@@ -1,21 +1,34 @@
 namespace FSharp.Formatting.Markdown
 
+/// <summary>
+/// Represents a source range in a Markdown document, identified by start and end line/column positions.
+/// Used to track where each parsed element originated in the source text.
+/// </summary>
 [<Struct>]
 type MarkdownRange =
-    { StartLine: int
-      StartColumn: int
-      EndLine: int
-      EndColumn: int }
+    {
+        /// The 1-based line number where the element starts
+        StartLine: int
+        /// The 0-based column index where the element starts
+        StartColumn: int
+        /// The 1-based line number where the element ends
+        EndLine: int
+        /// The 0-based column index where the element ends
+        EndColumn: int
+    }
 
 
+/// Helper functions for working with <see cref="MarkdownRange"/> values
 module MarkdownRange =
 
+    /// A zero range used as a default/placeholder when no real range is available
     let zero =
         { StartLine = 0
           StartColumn = 0
           EndLine = 0
           EndColumn = 0 }
 
+    /// Merges a list of ranges into one spanning range that covers all of them
     let mergeRanges (ranges: MarkdownRange list) =
         let startRange = ranges |> List.minBy (fun r -> r.StartLine, r.StartColumn)
 

src/FSharp.Formatting.Markdown/MarkdownFormatting.fs

@@ -2,13 +2,16 @@
 // Format a document as a .md
 // --------------------------------------------------------------------------------------
 
+/// Internal module for re-serializing a parsed Markdown AST back to Markdown text
 module internal FSharp.Formatting.Markdown.MarkdownFormatting
 
 open MarkdownUtils
 
+/// Formats a list of paragraphs, collecting all output lines
 let rec formatParagraphs ctx (paragraphs: MarkdownParagraph list) =
     paragraphs |> Seq.collect (formatParagraph ctx)
 
+/// Formats a full Markdown document as a Markdown string
 let formatAsMarkdown links replacements newline crefResolver mdlinkResolver paragraphs =
     let ctx =
         { Links = links