[Repo Assist] Add /// doc comments to CrossReferenceResolver.fs, CodeFormatAgent.fs, and YaafFSharpScripting.fs (issue #1035) (#1076)

* Add `///` doc comments to CrossReferenceResolver.fs, CodeFormatAgent.fs, YaafFSharpScripting.fs (issue #1035)

- CrossReferenceResolver.fs: docs for all private helpers and public member methods
- CodeFormatAgent.fs: module-level doc plus docs for key functions
- YaafFSharpScripting.fs: docs for Env, Log, CompilerServiceExtensions, output types

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>

Author: github-actions[bot]

src/FSharp.Formatting.ApiDocs/CrossReferenceResolver.fs

@@ -154,6 +154,8 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
     let niceNameEntityLookup = Dictionary<_, _>()
     let extensions = extensions
 
+    /// Generates a unique, filesystem-safe URL base name for the given symbol name by
+    /// replacing invalid characters and appending a numeric suffix when the name collides.
     let nameGen (name: string) =
         let nice =
             (toReplace
@@ -172,6 +174,7 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
         usedNames.Add(found, true)
         found
 
+    /// Registers the XML doc signature for a member so it can be looked up during cross-reference resolution.
     let registerMember (memb: FSharpMemberOrFunctionOrValue) =
         let xmlsig = getXmlDocSigForMember memb
 
@@ -184,6 +187,8 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
 
             xmlDocNameToSymbol.[xmlsig] <- memb
 
+    /// Recursively registers an entity and all its nested entities and members so they can
+    /// be resolved as cross-references. Assigns a unique URL base name to each entity.
     let rec registerEntity (entity: FSharpEntity) =
         let newName = nameGen (sprintf "%s.%s" entity.AccessPath entity.CompiledName)
 
@@ -205,12 +210,15 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
         for memb in entity.TryGetMembersFunctionsAndValues() do
             registerMember memb
 
+    /// Returns the previously-assigned URL base name for a registered entity,
+    /// raising an exception if the entity has not been registered.
     let getUrlBaseNameForRegisteredEntity (entity: FSharpEntity) =
         match registeredSymbolsToUrlBaseName.TryGetValue(entity) with
         | true, v -> v
         | _ ->
             failwithf "The entity %s was not registered before!" (sprintf "%s.%s" entity.AccessPath entity.CompiledName)
 
+    /// Strips a trailing parameter list "(…)" from a member name, returning just the base name.
     let removeParen (memberName: string) =
         let firstParen = memberName.IndexOf('(')
 
@@ -219,7 +227,7 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
         else
             memberName
 
-    // Strip generic parameters from a type name: "Map<K,V>" -> "Map", "List`1" -> "List"
+    /// Strips generic parameters from a type name, e.g. <c>"Map&lt;K,V&gt;"</c> → <c>"Map"</c>, <c>"List`1"</c> → <c>"List"</c>.
     let stripGenericSuffix (name: string) =
         let angleIdx = name.IndexOf('<')
         let backtickIdx = name.IndexOf('`')
@@ -233,6 +241,8 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
 
         name.Substring(0, cutAt)
 
+    /// Extracts the containing type name from a fully-qualified member name, e.g.
+    /// <c>"Ns.Type.Member(args)"</c> → <c>Some "Ns.Type"</c>; returns <c>None</c> if no period is found.
     let tryGetTypeFromMemberName (memberName: string) =
         let sub = removeParen memberName
         let lastPeriod = sub.LastIndexOf('.')
@@ -242,6 +252,8 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
         else
             None
 
+    /// Extracts the short member name (without the containing type prefix) from a fully-qualified
+    /// member name, e.g. <c>"Ns.Type.Member(args)"</c> → <c>Some "Member(args)"</c>.
     let tryGetShortMemberNameFromMemberName (memberName: string) =
         let sub = removeParen memberName
         let lastPeriod = sub.LastIndexOf('.')
@@ -251,6 +263,8 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
         else
             None
 
+    /// Returns a display name for a member by retaining the last <paramref name="keepParts"/> dot-separated
+    /// segments and optionally stripping a trailing "Module" suffix from the first segment.
     let getMemberName keepParts hasModuleSuffix (memberNameNoParen: string) =
         let splits = memberNameNoParen.Split('.') |> Array.toList
 
@@ -278,6 +292,9 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
 
         noGenerics
 
+    /// Builds an external documentation link for an FSharp.Core or .NET symbol.
+    /// FSharp.Core symbols are linked to <c>fsharp.github.io/fsharp-core-docs</c>;
+    /// all other symbols are linked to <c>learn.microsoft.com/dotnet/api</c>.
     let externalDocsLink isMember simple (typeName: string) (fullName: string) =
         if
             fullName.StartsWith("FSharp.", StringComparison.Ordinal)
@@ -340,12 +357,16 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
               ReferenceLink = link
               NiceName = simple }
 
+    /// Returns the URL for a registered entity within this documentation collection.
     let internalCrossReference urlBaseName =
         ApiDocEntity.GetUrl(urlBaseName, root, collectionName, qualify, extensions.InUrl)
 
+    /// Returns the URL for a specific member of a registered entity within this documentation collection.
     let internalCrossReferenceForMember entityUrlBaseName (memb: FSharpMemberOrFunctionOrValue) =
         ApiDocMember.GetUrl(entityUrlBaseName, memb.DisplayName, root, collectionName, qualify, extensions.InUrl)
 
+    /// Tries to resolve a cross-reference for an FSharpEntity; returns an internal link if the entity
+    /// was registered, otherwise falls back to an external documentation link.
     let tryResolveCrossReferenceForEntity (entity: FSharpEntity) =
         match registeredSymbolsToUrlBaseName.TryGetValue(entity) with
         | true, _v ->
@@ -360,6 +381,8 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
             | None -> None
             | Some nm -> Some(externalDocsLink false entity.DisplayName nm nm)
 
+    /// Resolves a type cross-reference given its XML doc signature (must start with <c>"T:"</c>).
+    /// Checks the registered symbol map first, then falls back to the nice-name entity lookup.
     let resolveCrossReferenceForTypeByXmlSig (typeXmlSig: string) =
         assert (typeXmlSig.StartsWith("T:", StringComparison.Ordinal))
 
@@ -428,6 +451,8 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
                     let simple = getMemberName 1 false typeName
                     externalDocsLink false simple typeName typeName
 
+    /// Converts a registered <see cref="T:FSharp.Compiler.Symbols.FSharpMemberOrFunctionOrValue"/> to an
+    /// internal <see cref="T:FSharp.Formatting.ApiDocs.CrefReference"/>.
     let mfvToCref (mfv: FSharpMemberOrFunctionOrValue) =
         match mfv.DeclaringEntity with
         | None -> failwith $"%s{mfv.DisplayName} does not have a DeclaringEntity"
@@ -438,6 +463,8 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
               ReferenceLink = internalCrossReferenceForMember entityUrlBaseName mfv
               NiceName = declaringEntity.DisplayName + "." + mfv.DisplayName }
 
+    /// Tries to resolve a cross-reference for a member given its XML doc signature
+    /// (must start with <c>"M:"</c>, <c>"P:"</c>, <c>"F:"</c>, or <c>"E:"</c>).
     let tryResolveCrossReferenceForMemberByXmlSig (memberXmlSig: string) =
         assert
             (memberXmlSig.StartsWith("M:", StringComparison.Ordinal)
@@ -519,7 +546,8 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
                 None
 
 
-    // Try to resolve a cref that has no XML doc prefix (e.g. "MyType", "MyType.MyMember", "Map<K,V>")
+    /// Tries to resolve a cref that has no XML doc prefix (e.g. <c>"MyType"</c>, <c>"MyType.MyMember"</c>).
+    /// Attempts a "Type.Member" split first, then a bare type name lookup.
     let tryResolveUnqualifiedCref (cref: string) =
         let baseName = stripGenericSuffix cref
 
@@ -562,6 +590,8 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
                 | _ -> None
             | _ -> None
 
+    /// Resolves a <c>cref</c> string (with or without XML doc prefix such as <c>"T:"</c> or <c>"M:"</c>)
+    /// to a <see cref="T:FSharp.Formatting.ApiDocs.CrefReference"/>, or <c>None</c> if unresolvable.
     member _.ResolveCref(cref: string) =
         if (cref.Length < 2) then
             invalidArg "cref" (sprintf "the given cref: '%s' is invalid!" cref)
@@ -583,19 +613,25 @@ type internal CrossReferenceResolver(root, collectionName, qualify, extensions)
                 Log.warnf "Unresolved reference '%s'!" cref
                 None
 
+    /// Registers an entity (and all its nested entities and members) so that cross-references to it can be resolved.
     member _.RegisterEntity entity = registerEntity entity
 
+    /// Returns the URL base name that was assigned to the given registered entity.
     member _.ResolveUrlBaseNameForEntity entity =
         getUrlBaseNameForRegisteredEntity entity
 
+    /// Returns the URL base name for the entity if it has been registered, or <c>None</c>.
     member _.TryResolveUrlBaseNameForEntity(entity: FSharpEntity) =
         match registeredSymbolsToUrlBaseName.TryGetValue(entity) with
         | true, v -> Some v
         | _ -> None
 
+    /// Tries to resolve an <see cref="T:FSharp.Compiler.Symbols.FSharpEntity"/> to a cross-reference,
+    /// returning an internal reference if registered or an external link otherwise.
     member _.TryResolveEntity entity =
         tryResolveCrossReferenceForEntity entity
 
+    /// Returns <c>true</c> if the given cref resolves to an entity within this documentation collection.
     member x.IsLocal cref =
         match x.ResolveCref(cref) with
         | None -> false

src/FSharp.Formatting.CodeFormat/CodeFormatAgent.fs

@@ -17,10 +17,8 @@ open FSharp.Compiler.EditorServices
 open FSharp.Compiler.CodeAnalysis
 open FSharp.Compiler.Diagnostics
 
-// --------------------------------------------------------------------------------------
-// ?
-// --------------------------------------------------------------------------------------
-
+/// Internal helpers for tokenising, type-checking and annotating F# source code
+/// using the F# Compiler Service, producing coloured and tooltip-annotated token spans.
 module private Helpers =
 
     /// Mapping table that translates F# compiler representation to our union
@@ -40,8 +38,7 @@ module private Helpers =
         | FSharpTokenColorKind.Default
         | _ -> TokenKind.Default
 
-    // Parse command line options - split string by space, but if there is something
-    // enclosed in double quotes "..." then ignore spaces in the quoted text
+    /// Parses compiler command-line options by splitting on spaces while respecting quoted strings.
     let parseOptions (str: string) =
         let rec loop i opts current =
             let opts =
@@ -107,8 +104,8 @@ module private Helpers =
 
         indexedSnippetLines
 
-    // Count the minimal number of spaces at the beginning of lines
-    // (so that we can remove spaces for indented text)
+    /// Returns the number of leading spaces on the least-indented non-empty line in the snippet,
+    /// used to strip common indentation when formatting indented code blocks.
     let countStartingSpaces (lines: Snippet) =
         [ for _, toks: _ list in lines do
               match toks with
@@ -118,6 +115,7 @@ module private Helpers =
               | _ -> yield 0 ]
         |> List.fold min 0
 
+/// A column range within a single source line, used to track string literal extents during tokenisation.
 [<Struct>]
 type internal Range =
     { LeftCol: int
@@ -127,15 +125,19 @@ type internal Range =
         { LeftCol = leftCol
           RightCol = rightCol }
 
-/// Uses agent to handle formatting requests
+/// Formats F# source code snippets into annotated token sequences by invoking the
+/// F# Compiler Service for tokenisation, type-checking, and semantic classification.
 module CodeFormatter =
-    // Create keys for query tooltips for double-backtick identifiers
+    /// Converts a double-backtick identifier like <c>``my ident``</c> into the form
+    /// <c>( my ident )</c> that the compiler uses for tooltip lookup.
     let processDoubleBackticks (body: string) =
         if body.StartsWith("``", StringComparison.Ordinal) then
             sprintf "( %s )" <| body.Trim '`'
         else
             body
 
+    /// Maps an FCS <see cref="T:FSharp.Compiler.EditorServices.SemanticClassificationType"/> to our
+    /// <see cref="T:FSharp.Formatting.CodeFormat.TokenKind"/>, or <c>None</c> for unrecognised categories.
     let categoryToTokenKind =
         function
         | SemanticClassificationType.Enumeration -> Some TokenKind.Enumeration
@@ -178,7 +180,8 @@ module CodeFormatter =
         | _ -> None
 
 
-    // Processes a single line of the snippet
+    /// Processes a single source line: walks the token stream and enriches each token with
+    /// semantic classification (colour kind and tooltip) from the FCS type-check results.
     let processSnippetLine
         (checkResults: FSharpCheckFileResults)
         (semanticRanges: SemanticClassificationItem array)
@@ -319,7 +322,8 @@ module CodeFormatter =
         // Process the current line & return info about it
         Line(lineStr, loop [] (List.ofSeq lineTokens) None |> List.ofSeq)
 
-    /// Process snippet
+    /// Processes all lines of a snippet using the FCS check results and semantic classification ranges,
+    /// returning an annotated list of <see cref="T:FSharp.Formatting.CodeFormat.Line"/> values.
     let processSnippet checkResults categorizedRanges lines (snippet: Snippet) =
         snippet
         |> List.map (fun snippetLine ->
@@ -336,12 +340,11 @@ module CodeFormatter =
 
     // --------------------------------------------------------------------------------------
 
-    // Create an instance of an InteractiveChecker (which does background analysis
-    // in a typical IntelliSense editor integration for F#)
+    /// Shared <see cref="T:FSharp.Compiler.CodeAnalysis.FSharpChecker"/> instance used for all source-code processing.
     let fsChecker = FSharpAssemblyHelper.checker // FSharpChecker.Create()
 
-    // ------------------------------------------------------------------------------------
-
+    /// Asynchronously parses, type-checks, and annotates a single F# source file or script,
+    /// returning an array of named, token-annotated snippets and any compilation diagnostics.
     let processSourceCode (filePath, source, options, defines, onError) =
         async {
             Log.verbf "starting to process source code from '%s'" filePath