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

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

Author: MariusStorhaug

src/functions/private/Confirm-YamlScalarLength.ps1

@@ -2,12 +2,27 @@ function Confirm-YamlScalarLength {
     <#
         .SYNOPSIS
         Enforces the configured length limit for an emission scalar.
+
+        .DESCRIPTION
+        Checks a scalar node against the active serializer length budget before
+        emission. This prevents generated YAML from silently exceeding the
+        configured maximum scalar size.
+
+        .EXAMPLE
+        Confirm-YamlScalarLength -Node ([pscustomobject]@{ Value = 'name' }) -State ([pscustomobject]@{ MaxScalarLength = 1024 })
+
+        Returns nothing because the scalar value is within the configured limit.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/ConvertTo-Yaml/
     #>
     [CmdletBinding()]
     param (
+        # The scalar node whose text length must fit the emission budget.
         [Parameter(Mandatory)]
         [pscustomobject] $Node,
 
+        # The serializer state that carries the configured maximum scalar length.
         [Parameter(Mandatory)]
         [pscustomobject] $State
     )

src/functions/private/ConvertTo-YamlFlowText.ps1

@@ -2,13 +2,28 @@ function ConvertTo-YamlFlowText {
     <#
         .SYNOPSIS
         Iteratively renders one emission graph in flow form.
+
+        .DESCRIPTION
+        Renders an emission node graph as a single flow-style YAML fragment for
+        scalar values, empty collections, implicit keys, and aliases. It tracks
+        already-emitted references so repeated nodes become aliases when needed.
+
+        .EXAMPLE
+        ConvertTo-YamlFlowText -Node $entry.Key -EmittedReferences $emittedReferences
+
+        Returns flow-style text for the mapping key, using an alias when already emitted.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/ConvertTo-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param (
+        # The emission node that must be rendered inline as flow YAML.
         [Parameter(Mandatory)]
         [pscustomobject] $Node,
 
+        # Tracks reference ids already written so aliases are emitted correctly.
         [Parameter(Mandatory)]
         [AllowEmptyCollection()]
         [System.Collections.Generic.HashSet[long]] $EmittedReferences

src/functions/private/ConvertTo-YamlNode.ps1

@@ -2,21 +2,39 @@ function ConvertTo-YamlNode {
     <#
         .SYNOPSIS
         Iteratively normalizes a supported PowerShell value to an emission graph.
+
+        .DESCRIPTION
+        Walks a supported PowerShell object graph without recursion and produces
+        the internal emission nodes consumed by the YAML writer. The state object
+        enforces resource limits, reference identity, anchors, and duplicate-key checks.
+
+        .EXAMPLE
+        ConvertTo-YamlNode -Value $inputObject -State $serializationState -Depth 1 -EnumsAsStrings
+
+        Returns the root emission node for the input object graph, using enum names when requested.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/ConvertTo-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([pscustomobject])]
     param (
+        # The PowerShell value that needs a YAML-safe emission representation.
         [Parameter(Mandatory)]
         [AllowNull()]
         [object] $Value,
 
+        # Carries serialization limits, reference tracking, and shared caches.
         [Parameter(Mandatory)]
         [pscustomobject] $State,
 
+        # Current graph depth used to enforce the configured maximum depth.
         [Parameter(Mandatory)]
         [ValidateRange(1, 2147483647)]
         [int] $Depth,
 
+        # Allows enum values to be emitted by name instead of underlying number.
+        [Parameter()]
         [switch] $EnumsAsStrings
     )
 

src/functions/private/ConvertTo-YamlQuotedText.ps1

@@ -2,10 +2,24 @@ function ConvertTo-YamlQuotedText {
     <#
         .SYNOPSIS
         Encodes a string as a YAML double-quoted scalar.
+
+        .DESCRIPTION
+        Escapes string content for a YAML double-quoted scalar, including control
+        characters and invalid UTF-16 surrogate detection. It is used when plain
+        scalar output would be ambiguous or unsafe.
+
+        .EXAMPLE
+        ConvertTo-YamlQuotedText -Value "line`nbreak"
+
+        Returns a YAML double-quoted scalar with required escape sequences.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/ConvertTo-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param (
+        # The scalar content to quote while preserving empty strings exactly.
         [Parameter(Mandatory)]
         [AllowEmptyString()]
         [string] $Value

src/functions/private/ConvertTo-YamlRepresentationNode.ps1

@@ -2,13 +2,28 @@ function ConvertTo-YamlRepresentationNode {
     <#
         .SYNOPSIS
         Converts one representation graph to a lossless emission graph.
+
+        .DESCRIPTION
+        Copies a parsed representation graph into the emission graph shape expected
+        by the writer while preserving node identity, tags, anchors, and aliases.
+        It assigns deterministic anchor names so formatted YAML remains stable.
+
+        .EXAMPLE
+        ConvertTo-YamlRepresentationNode -Node $document.Root -State $emissionState
+
+        Returns an emission node graph for the representation document.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/ConvertTo-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([pscustomobject])]
     param (
+        # The representation graph root that must be copied for emission.
         [Parameter(Mandatory)]
         [pscustomobject] $Node,
 
+        # Carries anchor numbering so names stay unique across emitted documents.
         [Parameter(Mandatory)]
         [pscustomobject] $State
     )

src/functions/private/ConvertTo-YamlRepresentationText.ps1

@@ -2,14 +2,29 @@ function ConvertTo-YamlRepresentationText {
     <#
         .SYNOPSIS
         Emits representation documents as deterministic LF-normalized YAML.
+
+        .DESCRIPTION
+        Converts composed representation documents into deterministic YAML text
+        without projecting through public PowerShell values. It supports
+        representation-preserving commands that must retain tags, anchors, and aliases.
+
+        .EXAMPLE
+        ConvertTo-YamlRepresentationText -Documents $documents -Indent 2
+
+        Returns the formatted YAML stream for all supplied representation documents.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/ConvertTo-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param (
+        # The representation document roots to emit in their original stream order.
         [Parameter(Mandatory)]
         [AllowEmptyCollection()]
         [object[]] $Documents,
 
+        # Number of spaces per nesting level for deterministic block output.
         [Parameter(Mandatory)]
         [ValidateRange(2, 9)]
         [int] $Indent

src/functions/private/ConvertTo-YamlTagText.ps1

@@ -2,10 +2,24 @@ function ConvertTo-YamlTagText {
     <#
         .SYNOPSIS
         Encodes an effective tag as canonical YAML tag text.
+
+        .DESCRIPTION
+        Escapes an expanded effective tag as YAML tag presentation text, using
+        standard shorthand when possible. This keeps representation graph output
+        deterministic while preserving local and application tags verbatim.
+
+        .EXAMPLE
+        ConvertTo-YamlTagText -Tag 'tag:yaml.org,2002:str'
+
+        Returns !!str for the standard YAML string tag.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/ConvertTo-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param (
+        # The expanded effective tag URI that must be encoded for YAML output.
         [Parameter(Mandatory)]
         [string] $Tag
     )

src/functions/private/ConvertTo-YamlText.ps1

@@ -2,17 +2,34 @@ function ConvertTo-YamlText {
     <#
         .SYNOPSIS
         Emits an internal node graph as LF-normalized YAML text.
+
+        .DESCRIPTION
+        Serializes a normalized emission node graph to a YAML document using LF
+        line endings and the configured indentation. It centralizes final text
+        assembly so document markers, anchors, and aliases are emitted consistently.
+
+        .EXAMPLE
+        ConvertTo-YamlText -Node $emissionNode -Indent 2 -ExplicitDocumentStart
+
+        Returns YAML text for the emission graph with an explicit document start marker.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/ConvertTo-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param (
+        # The root emission graph to write as one YAML document.
         [Parameter(Mandatory)]
         [pscustomobject] $Node,
 
+        # Number of spaces per nesting level for deterministic block output.
         [Parameter(Mandatory)]
         [ValidateRange(2, 9)]
         [int] $Indent,
 
+        # Allows callers to include the YAML document-start marker when required.
+        [Parameter()]
         [switch] $ExplicitDocumentStart
     )
 

src/functions/private/ConvertTo-YamlTimestampText.ps1

@@ -2,10 +2,24 @@ function ConvertTo-YamlTimestampText {
     <#
         .SYNOPSIS
         Formats a representable CLR timestamp for YAML emission.
+
+        .DESCRIPTION
+        Formats DateTime and DateTimeOffset values with invariant timestamp text
+        accepted by the YAML emitter. It preserves explicit or local offsets when
+        representable and normalizes unspecified timestamps to UTC-style text.
+
+        .EXAMPLE
+        ConvertTo-YamlTimestampText -Value ([datetimeoffset] '2026-07-26T20:51:03+00:00')
+
+        Returns invariant YAML timestamp text for the supplied CLR timestamp.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/ConvertTo-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([string])]
     param (
+        # The CLR timestamp value to validate and format for YAML output.
         [Parameter(Mandatory)]
         [object] $Value
     )

src/functions/private/Get-YamlEmissionImplicitKeyLength.ps1

@@ -2,10 +2,24 @@ function Get-YamlEmissionImplicitKeyLength {
     <#
         .SYNOPSIS
         Gets an emitted implicit key length in Unicode scalar values.
+
+        .DESCRIPTION
+        Counts Unicode scalar values in the already rendered key text. The emitter uses this to
+        enforce YAML 1.2 implicit key length limits before choosing implicit or explicit key
+        presentation.
+
+        .EXAMPLE
+        Get-YamlEmissionImplicitKeyLength -RenderedText 'name'
+
+        Returns the number of Unicode scalar values that the rendered implicit key would occupy.
+
+        .LINK
+        https://psmodule.io/Yaml/Functions/ConvertTo-Yaml/
     #>
     [CmdletBinding()]
     [OutputType([int])]
     param (
+        # The rendered key text is measured after escaping so the limit matches emitted YAML.
         [Parameter(Mandatory)]
         [AllowEmptyString()]
         [string] $RenderedText