Add comment-based help and inline parameter docs to Merge-Yaml private helpers

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

Author: MariusStorhaug

src/functions/private/Add-YamlMergeIndexCandidate.ps1

@@ -2,15 +2,33 @@ function Add-YamlMergeIndexCandidate {
     <#
         .SYNOPSIS
         Adds one mapping key or sequence item to a structural candidate index.
+
+        .DESCRIPTION
+        Adds a mapping entry or sequence item to an index bucket keyed by a
+        structural fingerprint. It tracks effective node identities and
+        dependencies so later mutations can invalidate only indexes that may be
+        stale.
+
+        .EXAMPLE
+        Add-YamlMergeIndexCandidate -Index $mappingIndex -Candidate $entry -Context $mergeContext
+
+        Indexes the entry's key as a candidate for future structural equality
+        lookups.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Merge-Yaml/
     #>
     [CmdletBinding()]
     param (
+        # The candidate index receiving the mapping key or sequence item.
         [Parameter(Mandatory)]
         [pscustomobject] $Index,
 
+        # The entry or item to index for later structural equality lookup.
         [Parameter(Mandatory)]
         [pscustomobject] $Candidate,
 
+        # Shared merge context provides work accounting and fingerprint/equality state.
         [Parameter(Mandatory)]
         [pscustomobject] $Context
     )

src/functions/private/Add-YamlMergeWork.ps1

@@ -2,19 +2,38 @@ function Add-YamlMergeWork {
     <#
         .SYNOPSIS
         Charges one or more deterministic operations to the YAML merge work budget.
+
+        .DESCRIPTION
+        Increments the invocation work counter for deterministic merge operations
+        such as indexing, fingerprinting, equality checks, and cloning. This
+        centralizes budget enforcement so adversarial graphs cannot make merge
+        processing unbounded.
+
+        .EXAMPLE
+        Add-YamlMergeWork -State $mergeContext.WorkState -Count 3 -Operation 'index rebuild' -Node $node
+
+        Charges three index rebuild operations to the merge budget and throws if
+        the configured limit is exceeded.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Merge-Yaml/
     #>
     [CmdletBinding()]
     param (
+        # Shared work budget state records total charged operations.
         [Parameter(Mandatory)]
         [pscustomobject] $State,
 
+        # Allows callers to charge batched deterministic work without repeated calls.
         [Parameter()]
         [ValidateRange(1, 2147483647)]
         [int] $Count = 1,
 
+        # Names the work being charged for precise limit diagnostics.
         [Parameter(Mandatory)]
         [string] $Operation,
 
+        # Supplies source location for limit errors when a specific graph node caused the work.
         [Parameter()]
         [AllowNull()]
         [pscustomobject] $Node

src/functions/private/Assert-YamlMergeGraph.ps1

@@ -2,28 +2,50 @@ function Assert-YamlMergeGraph {
     <#
         .SYNOPSIS
         Validates the merged representation graph and its resource budgets.
+
+        .DESCRIPTION
+        Walks merged documents to enforce final depth, node, alias, scalar, and
+        tag budgets before emission. It also delegates graph validation so
+        recursive or shared representation structures remain safe and well-formed
+        after merging.
+
+        .EXAMPLE
+        Assert-YamlMergeGraph -Documents $mergedDocuments -Depth 100 -MaxNodes 100000 -MaxAliases 1000 -MaxScalarLength 1048576 -MaxTagLength 1024 -MaxTotalTagLength 65536
+
+        Validates the merged document graph and throws a classified YAML merge
+        exception if any limit is exceeded.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Merge-Yaml/
     #>
     [CmdletBinding()]
     param (
+        # The merged document roots to validate as one resulting YAML stream.
         [Parameter(Mandatory)]
         [AllowEmptyCollection()]
         [object[]] $Documents,
 
+        # Limits traversal depth so deeply nested results cannot exhaust consumers.
         [Parameter(Mandatory)]
         [int] $Depth,
 
+        # Caps unique representation nodes in the result graph.
         [Parameter(Mandatory)]
         [int] $MaxNodes,
 
+        # Caps alias nodes after merge to keep reference expansion bounded.
         [Parameter(Mandatory)]
         [int] $MaxAliases,
 
+        # Caps decoded scalar size before the merged stream is emitted.
         [Parameter(Mandatory)]
         [int] $MaxScalarLength,
 
+        # Caps each expanded tag length in the merged graph.
         [Parameter(Mandatory)]
         [int] $MaxTagLength,
 
+        # Caps cumulative expanded tag text across the result graph.
         [Parameter(Mandatory)]
         [int] $MaxTotalTagLength
     )

src/functions/private/Copy-YamlMergeNode.ps1

@@ -2,6 +2,21 @@ function Copy-YamlMergeNode {
     <#
         .SYNOPSIS
         Deep-clones a YAML representation graph with identity memoization.
+
+        .DESCRIPTION
+        Deep-clones a representation node and descendants into the merge working
+        graph so overlays never mutate caller-owned input graphs. Identity
+        memoization preserves shared and cyclic references while enforcing clone
+        creation budgets.
+
+        .EXAMPLE
+        Copy-YamlMergeNode -Node $overlayNode -Cache $mergeContext.CloneCache -State $mergeContext.CloneState
+
+        Returns an independent clone of the overlay node registered in the merge
+        clone cache.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Merge-Yaml/
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '',
@@ -10,13 +25,16 @@ function Copy-YamlMergeNode {
     [CmdletBinding()]
     [OutputType([pscustomobject])]
     param (
+        # The representation graph root to clone into merge-owned storage.
         [Parameter(Mandatory)]
         [pscustomobject] $Node,
 
+        # Memoizes source-to-clone identity so aliases, sharing, and cycles are preserved.
         [Parameter(Mandatory)]
         [AllowEmptyCollection()]
         [System.Collections.Generic.Dictionary[int, object]] $Cache,
 
+        # Tracks clone IDs and creation limits for the isolated working graph.
         [Parameter(Mandatory)]
         [pscustomobject] $State
     )

src/functions/private/Find-YamlMergeIndexMatch.ps1

@@ -2,16 +2,33 @@ function Find-YamlMergeIndexMatch {
     <#
         .SYNOPSIS
         Finds a collision-safe structural match in a YAML merge candidate index.
+
+        .DESCRIPTION
+        Looks up a node's structural fingerprint in a candidate index and verifies
+        any bucket collisions with full graph equality. This makes mapping-key and
+        unique-sequence matching fast without trusting hashes as equality.
+
+        .EXAMPLE
+        Find-YamlMergeIndexMatch -Index $retainedIndex -Node $overlayEntry.Key -Context $mergeContext
+
+        Returns the matching retained entry when the overlay key is structurally
+        equal, or nothing when no match exists.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Merge-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([pscustomobject])]
     param (
+        # The retained candidate index narrows possible structural matches.
         [Parameter(Mandatory)]
         [pscustomobject] $Index,
 
+        # The overlay key or sequence item to match against retained candidates.
         [Parameter(Mandatory)]
         [pscustomobject] $Node,
 
+        # Shared merge context supplies fingerprint caches, equality state, and work limits.
         [Parameter(Mandatory)]
         [pscustomobject] $Context
     )

src/functions/private/Get-YamlMergeFingerprint.ps1

@@ -2,20 +2,40 @@ function Get-YamlMergeFingerprint {
     <#
         .SYNOPSIS
         Creates a deterministic structural candidate index for merge comparisons.
+
+        .DESCRIPTION
+        Computes a deterministic structural fingerprint for a representation
+        subgraph, resolving aliases and accounting for cycles without requiring
+        object projection. The fingerprint narrows candidate comparisons for
+        indexes and equality, while collision safety is provided by subsequent
+        graph equality checks.
+
+        .EXAMPLE
+        Get-YamlMergeFingerprint -Node $entry.Key -State $mergeContext.EqualityState -Cache $fingerprintCache -CandidateIndex $mappingIndex
+
+        Returns a deterministic hash used to place the key in a structural
+        candidate bucket.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Merge-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param (
+        # The subgraph root whose structure needs a candidate fingerprint.
         [Parameter(Mandatory)]
         [pscustomobject] $Node,
 
+        # Provides hashing resources, work accounting, and index dependency maps.
         [Parameter(Mandatory)]
         [pscustomobject] $State,
 
+        # Reuses fingerprints for acyclic nodes to avoid repeated traversal work.
         [Parameter()]
         [AllowNull()]
         [System.Collections.Generic.Dictionary[int, string]] $Cache,
 
+        # Records node dependencies so mutations can invalidate this index.
         [Parameter()]
         [AllowNull()]
         [pscustomobject] $CandidateIndex

src/functions/private/Get-YamlMergeIndex.ps1

@@ -2,17 +2,35 @@ function Get-YamlMergeIndex {
     <#
         .SYNOPSIS
         Gets or rebuilds a mutation-aware structural candidate index.
+
+        .DESCRIPTION
+        Retrieves the cached structural candidate index for a mapping or sequence,
+        rebuilding it when mutations invalidated prior buckets. It lets recursive
+        merge operations reuse fingerprint buckets while remaining correct after
+        graph changes.
+
+        .EXAMPLE
+        Get-YamlMergeIndex -Node $baseMapping -Kind Mapping -Context $mergeContext
+
+        Returns a valid mapping index for matching overlay keys against retained
+        entries.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Merge-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([pscustomobject])]
     param (
+        # The mapping or sequence node whose retained candidates need indexing.
         [Parameter(Mandatory)]
         [pscustomobject] $Node,
 
+        # Selects whether entries or items are indexed for this node.
         [Parameter(Mandatory)]
         [ValidateSet('Mapping', 'Sequence')]
         [string] $Kind,
 
+        # Provides index caches, dependency tracking, and work accounting.
         [Parameter(Mandatory)]
         [pscustomobject] $Context
     )

src/functions/private/Get-YamlMergeNode.ps1

@@ -2,10 +2,25 @@ function Get-YamlMergeNode {
     <#
         .SYNOPSIS
         Resolves aliases to their effective YAML representation node.
+
+        .DESCRIPTION
+        Follows alias targets until the effective representation node is reached.
+        Merge comparison, indexing, and mutation bookkeeping use this canonical
+        node so aliases do not create false differences.
+
+        .EXAMPLE
+        Get-YamlMergeNode -Node $aliasNode
+
+        Returns the alias target node, or the original node when it is not an
+        alias.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Merge-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([pscustomobject])]
     param (
+        # The node to canonicalize before merge bookkeeping or comparison.
         [Parameter(Mandatory)]
         [pscustomobject] $Node
     )

src/functions/private/Get-YamlMergeNodeTag.ps1

@@ -2,10 +2,25 @@ function Get-YamlMergeNodeTag {
     <#
         .SYNOPSIS
         Gets the effective tag used for YAML merge compatibility.
+
+        .DESCRIPTION
+        Resolves aliases and returns the effective YAML tag used to decide merge
+        compatibility. Scalars are resolved first so implicit tags reflect
+        constructed values rather than presentation text.
+
+        .EXAMPLE
+        Get-YamlMergeNodeTag -Node $candidateNode
+
+        Returns the effective tag, such as tag:yaml.org,2002:str, for merge
+        comparisons.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Merge-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param (
+        # The representation node whose effective compatibility tag is needed.
         [Parameter(Mandatory)]
         [pscustomobject] $Node
     )

src/functions/private/Get-YamlMergePath.ps1

@@ -2,16 +2,33 @@ function Get-YamlMergePath {
     <#
         .SYNOPSIS
         Creates a stable diagnostic path for one YAML mapping entry.
+
+        .DESCRIPTION
+        Builds a stable human-readable path for a child mapping key during
+        recursive merge conflict reporting. Scalar string keys use property or
+        quoted-index syntax, while complex keys fall back to deterministic entry
+        indexes.
+
+        .EXAMPLE
+        Get-YamlMergePath -Parent '$.spec' -Key $entry.Key -Index 2
+
+        Returns a diagnostic child path such as $.spec.name or $.spec{key:2}.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Merge-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param (
+        # Carries the already-resolved parent path for nested diagnostics.
         [Parameter(Mandatory)]
         [string] $Parent,
 
+        # Determines the child path segment from the overlay mapping key.
         [Parameter(Mandatory)]
         [pscustomobject] $Key,
 
+        # Provides a deterministic fallback when the key is not a simple string.
         [Parameter(Mandatory)]
         [int] $Index
     )