Add comment-based help and inline parameter docs to Remove-YamlEntry private helpers

MariusStorhaug · Copilot · MariusStorhaug · commit 56337dab6b55 · 2026-07-26T22:53:54.000+02:00
Co-authored-by: Copilot App &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/src/functions/private/Add-YamlRemovalWork.ps1 b/src/functions/private/Add-YamlRemovalWork.ps1
@@ -2,19 +2,40 @@ function Add-YamlRemovalWork {
     <#
         .SYNOPSIS
         Charges deterministic operations to the YAML removal work budget.
+
+        .DESCRIPTION
+        Increments the shared work counter for expensive removal steps.
+        Centralizing the charge keeps pointer resolution, coalescing, mutation,
+        and validation on one deterministic budget and produces a
+        location-aware exception when exceeded.
+
+        .EXAMPLE
+        Add-YamlRemovalWork -State $state -Count 3 -Operation 'target ordering' -Node $target.Node
+
+        Charges three target-ordering operations and throws if the removal budget is exceeded.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Remove-YamlEntry/
     #>
     [CmdletBinding()]
     param (
+        # The shared state carries current and maximum work counts for the
+        # removal invocation.
         [Parameter(Mandatory)]
         [pscustomobject] $State,
 
+        # The operation cost is configurable because some steps charge a batch
+        # of work at once.
         [Parameter()]
         [ValidateRange(1, 2147483647)]
         [int] $Count = 1,
 
+        # The operation name explains which removal phase consumed the budget.
         [Parameter(Mandatory)]
         [string] $Operation,
 
+        # The optional node anchors any budget exception to the YAML source
+        # location.
         [Parameter()]
         [AllowNull()]
         [pscustomobject] $Node
diff --git a/src/functions/private/Assert-YamlRemovalGraph.ps1 b/src/functions/private/Assert-YamlRemovalGraph.ps1
@@ -2,31 +2,61 @@ function Assert-YamlRemovalGraph {
     <#
         .SYNOPSIS
         Validates a removed representation graph and its resource budgets.
+
+        .DESCRIPTION
+        Traverses the post-removal representation graph to enforce depth, node,
+        alias, scalar, and tag limits before emitting YAML. It also rechecks
+        tagged collection invariants and duplicate-key comparisons so removed
+        output remains valid and deterministic.
+
+        .EXAMPLE
+        Assert-YamlRemovalGraph -Documents $documents -Depth 100 -MaxNodes 100000 -MaxAliases 1000 -MaxScalarLength 1048576 -MaxTagLength 1024 -MaxTotalTagLength 65536 -State $state
+
+        Validates the mutated documents and throws a classified removal exception if an output limit is exceeded.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Remove-YamlEntry/
     #>
     [CmdletBinding()]
     param (
+        # The post-removal document roots are walked so validation covers exactly
+        # what will be emitted.
         [Parameter(Mandatory)]
         [AllowEmptyCollection()]
         [object[]] $Documents,
 
+        # The depth limit prevents a removal result from producing an over-deep
+        # graph.
         [Parameter(Mandatory)]
         [int] $Depth,
 
+        # The node limit bounds traversal, duplicate-key comparison, and output
+        # graph size.
         [Parameter(Mandatory)]
         [int] $MaxNodes,
 
+        # The alias limit keeps emitted alias count within the caller's resource
+        # budget.
         [Parameter(Mandatory)]
         [int] $MaxAliases,
 
+        # The scalar length limit rejects oversized decoded scalar content after
+        # mutation.
         [Parameter(Mandatory)]
         [int] $MaxScalarLength,
 
+        # The per-tag limit prevents an emitted node from carrying an oversized
+        # expanded tag.
         [Parameter(Mandatory)]
         [int] $MaxTagLength,
 
+        # The cumulative tag limit bounds total expanded tag text across the
+        # output graph.
         [Parameter(Mandatory)]
         [int] $MaxTotalTagLength,
 
+        # The shared removal work state accounts validation operations against
+        # the invocation budget.
         [Parameter(Mandatory)]
         [pscustomobject] $State
     )
diff --git a/src/functions/private/ConvertFrom-YamlJsonPointer.ps1 b/src/functions/private/ConvertFrom-YamlJsonPointer.ps1
@@ -2,14 +2,31 @@ function ConvertFrom-YamlJsonPointer {
     <#
         .SYNOPSIS
         Parses and strictly decodes one RFC 6901 JSON Pointer.
+
+        .DESCRIPTION
+        Validates that a removal path is an RFC 6901 JSON Pointer and decodes
+        each token's tilde escapes. Strict decoding prevents ambiguous or
+        non-standard paths from selecting unintended YAML graph edges.
+
+        .EXAMPLE
+        ConvertFrom-YamlJsonPointer -Pointer '/metadata/internal~1id' -State $state
+
+        Returns a boxed token array containing metadata and internal/id.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Remove-YamlEntry/
     #>
     [CmdletBinding()]
     [OutputType([pscustomobject])]
     param (
+        # The raw removal path must be decoded once so later graph resolution
+        # uses canonical tokens.
         [Parameter(Mandatory)]
         [AllowEmptyString()]
         [string] $Pointer,
 
+        # The work state charges parsing by pointer length to keep path
+        # processing bounded.
         [Parameter(Mandatory)]
         [pscustomobject] $State
     )
diff --git a/src/functions/private/Get-YamlRemovalNode.ps1 b/src/functions/private/Get-YamlRemovalNode.ps1
@@ -2,13 +2,31 @@ function Get-YamlRemovalNode {
     <#
         .SYNOPSIS
         Resolves aliases to an effective YAML node with cycle-safe accounting.
+
+        .DESCRIPTION
+        Follows alias nodes until it reaches the effective scalar, sequence, or
+        mapping node used by removal logic. It records alias traversal work and
+        detects alias-only cycles or broken aliases so pointer walks cannot loop
+        forever.
+
+        .EXAMPLE
+        Get-YamlRemovalNode -Node $entry.Value -State $state
+
+        Returns the non-alias node that removal logic should inspect for the entry value.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Remove-YamlEntry/
     #>
     [CmdletBinding()]
     [OutputType([pscustomobject])]
     param (
+        # The candidate node may be an alias, so removal needs its effective
+        # target before inspecting kind or value.
         [Parameter(Mandatory)]
         [pscustomobject] $Node,
 
+        # The work state charges each alias hop and enforces traversal safety for
+        # this invocation.
         [Parameter(Mandatory)]
         [pscustomobject] $State
     )
diff --git a/src/functions/private/New-YamlRemovalException.ps1 b/src/functions/private/New-YamlRemovalException.ps1
@@ -2,6 +2,20 @@ function New-YamlRemovalException {
     <#
         .SYNOPSIS
         Creates a classified exception for a YAML removal failure.
+
+        .DESCRIPTION
+        Wraps removal failures in the module's YAML exception shape with the
+        correct error id and source marks. It falls back to a zero mark when no
+        node is available so budget and pointer parse failures remain
+        classified.
+
+        .EXAMPLE
+        New-YamlRemovalException -ErrorId 'YamlRemovalPathNotFound' -Message 'The path was not found.' -Node $node
+
+        Returns a classified exception whose source marks point at the supplied node.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Remove-YamlEntry/
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '',
@@ -10,12 +24,18 @@ function New-YamlRemovalException {
     [CmdletBinding()]
     [OutputType([System.FormatException])]
     param (
+        # The removal-specific error id classifies the failure for callers and
+        # tests.
         [Parameter(Mandatory)]
         [string] $ErrorId,
 
+        # The message explains the exact pointer, graph, or budget problem to
+        # report.
         [Parameter(Mandatory)]
         [string] $Message,
 
+        # The node supplies source marks when a graph location exists; null
+        # failures use a synthetic mark.
         [Parameter()]
         [AllowNull()]
         [pscustomobject] $Node
diff --git a/src/functions/private/Remove-YamlRepresentationTarget.ps1 b/src/functions/private/Remove-YamlRepresentationTarget.ps1
@@ -2,20 +2,40 @@ function Remove-YamlRepresentationTarget {
     <#
         .SYNOPSIS
         Applies resolved YAML removal targets in stable mutation order.
+
+        .DESCRIPTION
+        Mutates the cloned document list and container nodes for previously
+        resolved removal targets. It groups and sorts targets deepest-first and
+        descending by index so removing documents, sequence items, and mapping
+        entries does not shift later mutations.
+
+        .EXAMPLE
+        Remove-YamlRepresentationTarget -Documents $documents -Targets $targets -State $state
+
+        Detaches the resolved document, sequence, and mapping targets from the cloned representation graph.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Remove-YamlEntry/
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '',
         Justification = 'Mutates only an isolated in-memory representation graph.'
     )]
     [CmdletBinding()]
     param (
+        # The cloned document list is mutated when a target removes an entire
+        # YAML document.
         [Parameter(Mandatory)]
         [System.Collections.Generic.List[object]] $Documents,
 
+        # The resolved targets identify exact document, sequence, or mapping
+        # edges to detach.
         [Parameter(Mandatory)]
         [AllowEmptyCollection()]
         [object[]] $Targets,
 
+        # The work state charges ordering and mutation steps so transaction
+        # application is budgeted.
         [Parameter(Mandatory)]
         [pscustomobject] $State
     )
diff --git a/src/functions/private/Resolve-YamlRemovalTarget.ps1 b/src/functions/private/Resolve-YamlRemovalTarget.ps1
@@ -2,25 +2,49 @@ function Resolve-YamlRemovalTarget {
     <#
         .SYNOPSIS
         Resolves one decoded JSON Pointer against one YAML document.
+
+        .DESCRIPTION
+        Walks a single document's representation graph using decoded RFC 6901
+        tokens and returns the exact document, mapping, or sequence edge to
+        remove. It preserves YAML semantics by resolving aliases safely and
+        matching only scalar string mapping keys without coercion.
+
+        .EXAMPLE
+        Resolve-YamlRemovalTarget -Document $document -DocumentIndex 0 -Pointer '/service/obsolete' -Tokens @('service', 'obsolete') -State $state
+
+        Returns the parent edge that addresses /service/obsolete in document zero.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Remove-YamlEntry/
     #>
     [CmdletBinding()]
     [OutputType([pscustomobject])]
     param (
+        # The document root provides the representation graph that the pointer
+        # is resolved against.
         [Parameter(Mandatory)]
         [pscustomobject] $Document,
 
+        # The document index is included in target keys and diagnostics so
+        # multi-document removals stay distinct.
         [Parameter(Mandatory)]
         [int] $DocumentIndex,
 
+        # The original pointer is preserved for diagnostics attached to
+        # unresolved or ambiguous paths.
         [Parameter(Mandatory)]
         [AllowEmptyString()]
         [string] $Pointer,
 
+        # Decoded pointer tokens drive each mapping-key or sequence-index lookup
+        # without re-parsing the path.
         [Parameter(Mandatory)]
         [AllowEmptyCollection()]
         [AllowEmptyString()]
         [string[]] $Tokens,
 
+        # The shared work state bounds token resolution, alias traversal, and
+        # mapping scans.
         [Parameter(Mandatory)]
         [pscustomobject] $State
     )
diff --git a/src/functions/private/Select-YamlRemovalTarget.ps1 b/src/functions/private/Select-YamlRemovalTarget.ps1
@@ -2,14 +2,32 @@ function Select-YamlRemovalTarget {
     <#
         .SYNOPSIS
         Coalesces duplicate targets and drops fully subsumed descendants.
+
+        .DESCRIPTION
+        Combines multiple resolved removal requests that address the same edge
+        and removes descendants already covered by ancestor removals. This
+        prevents duplicate mutation attempts and keeps transaction ordering
+        stable.
+
+        .EXAMPLE
+        Select-YamlRemovalTarget -Targets $resolvedTargets -State $state
+
+        Returns a boxed target list with duplicates coalesced and ancestor-covered descendants removed.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/Remove-YamlEntry/
     #>
     [CmdletBinding()]
     [OutputType([pscustomobject])]
     param (
+        # The resolved target set may contain duplicate edges or descendant paths
+        # that one ancestor mutation will already remove.
         [Parameter(Mandatory)]
         [AllowEmptyCollection()]
         [object[]] $Targets,
 
+        # The work state accounts coalescing and ancestry indexing so target
+        # selection stays bounded.
         [Parameter(Mandatory)]
         [pscustomobject] $State
     )
