Skip to content

Commit b304dd3

Browse files
MariusStorhaugCopilot
MariusStorhaug
and
Copilot
committed
Align public function help and parameter blocks with the PowerShell Functions standard
Move parameter documentation into inline comments inside the param block, give every parameter an explicit [Parameter()] attribute, add .INPUTS/.OUTPUTS descriptions, and point the first .LINK at the psmodule.io reference page. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent b9fe5c3 commit b304dd3

8 files changed

Lines changed: 130 additions & 303 deletions

File tree

‎src/functions/public/ConvertFrom-Yaml.ps1‎

Lines changed: 27 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -12,40 +12,6 @@ function ConvertFrom-Yaml {
1212
Pipeline strings are joined with a line feed and parsed as one stream,
1313
which supports Get-Content. Each YAML document is written separately.
1414
15-
.PARAMETER Yaml
16-
YAML text. Multiple pipeline records are joined with a line feed and
17-
parsed as one YAML stream.
18-
19-
.PARAMETER AsHashtable
20-
Returns mappings as insertion-ordered dictionaries. Use this for
21-
complex, non-string, empty, or case-colliding mapping keys.
22-
23-
.PARAMETER NoEnumerate
24-
Writes each top-level YAML sequence as one array pipeline record.
25-
26-
.PARAMETER Depth
27-
Maximum YAML node nesting depth. The default is 100.
28-
29-
.PARAMETER MaxNodes
30-
Maximum number of YAML nodes in the stream. The default is 100000.
31-
32-
.PARAMETER MaxAliases
33-
Maximum number of alias nodes in the stream. The default is 1000.
34-
35-
.PARAMETER MaxScalarLength
36-
Maximum decoded character count for one scalar. The default is
37-
1048576.
38-
39-
.PARAMETER MaxTagLength
40-
Maximum expanded character count for one tag. The default is 1024.
41-
42-
.PARAMETER MaxTotalTagLength
43-
Maximum cumulative expanded tag characters. The default is 65536.
44-
45-
.PARAMETER MaxNumericLength
46-
Maximum digits in an implicitly or explicitly typed number. The
47-
default is 4096.
48-
4915
.EXAMPLE
5016
'name: Ada' | ConvertFrom-Yaml
5117
@@ -59,41 +25,67 @@ function ConvertFrom-Yaml {
5925
.INPUTS
6026
System.String[]
6127
28+
The YAML text to parse. Multiple pipeline records are joined with a line feed.
29+
6230
.OUTPUTS
6331
System.Object
6432
33+
The PowerShell value constructed from each YAML document in the stream.
34+
6535
.LINK
66-
https://github.com/PSModule/Yaml#parse-yaml
36+
https://psmodule.io/Yaml/Functions/ConvertFrom-Yaml/
6737
#>
6838
[CmdletBinding()]
6939
[OutputType([object])]
7040
param (
41+
# The YAML text to parse. Multiple pipeline records are joined with a
42+
# line feed and parsed as a single stream, which supports Get-Content.
7143
[Parameter(Mandatory, Position = 0, ValueFromPipeline)]
7244
[AllowEmptyString()]
7345
[string[]] $Yaml,
7446

47+
# Return mappings as insertion-ordered dictionaries so complex, non-string,
48+
# empty, or case-colliding keys survive intact.
49+
[Parameter()]
7550
[switch] $AsHashtable,
7651

52+
# Write each top-level sequence as a single array record instead of
53+
# enumerating its items onto the pipeline.
54+
[Parameter()]
7755
[switch] $NoEnumerate,
7856

57+
# Cap YAML node nesting depth so hostile input can't exhaust the stack.
58+
[Parameter()]
7959
[ValidateRange(1, 128)]
8060
[int] $Depth = 100,
8161

62+
# Cap the total node count to bound memory for a single stream.
63+
[Parameter()]
8264
[ValidateRange(1, 2147483647)]
8365
[int] $MaxNodes = 100000,
8466

67+
# Cap alias nodes to prevent alias-expansion amplification.
68+
[Parameter()]
8569
[ValidateRange(0, 2147483647)]
8670
[int] $MaxAliases = 1000,
8771

72+
# Cap decoded characters per scalar to bound per-node memory.
73+
[Parameter()]
8874
[ValidateRange(1, 2147483647)]
8975
[int] $MaxScalarLength = 1048576,
9076

77+
# Cap expanded characters for a single tag.
78+
[Parameter()]
9179
[ValidateRange(1, 1048576)]
9280
[int] $MaxTagLength = 1024,
9381

82+
# Cap cumulative expanded tag characters across the stream.
83+
[Parameter()]
9484
[ValidateRange(1, 2147483647)]
9585
[int] $MaxTotalTagLength = 65536,
9686

87+
# Cap the digit count of an implicitly or explicitly typed number.
88+
[Parameter()]
9789
[ValidateRange(1, 1048576)]
9890
[int] $MaxNumericLength = 4096
9991
)

‎src/functions/public/ConvertTo-Yaml.ps1‎

Lines changed: 20 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -12,28 +12,6 @@ function ConvertTo-Yaml {
1212
1313
Multiple pipeline records are collected into one top-level sequence.
1414
15-
.PARAMETER InputObject
16-
A value to serialize. Multiple pipeline records become one sequence.
17-
18-
.PARAMETER Depth
19-
Maximum object-graph nesting depth. The default is 100.
20-
21-
.PARAMETER MaxNodes
22-
Maximum number of traversed nodes. The default is 100000.
23-
24-
.PARAMETER MaxScalarLength
25-
Maximum character count for one emitted scalar. The default is
26-
1048576.
27-
28-
.PARAMETER Indent
29-
Block indentation from 2 through 9 spaces. The default is 2.
30-
31-
.PARAMETER ExplicitDocumentStart
32-
Emits an explicit `---` document start marker.
33-
34-
.PARAMETER EnumsAsStrings
35-
Emits enum names as strings instead of underlying numeric values.
36-
3715
.EXAMPLE
3816
[ordered]@{ name = 'Ada'; active = $true } | ConvertTo-Yaml
3917
@@ -47,33 +25,52 @@ function ConvertTo-Yaml {
4725
.INPUTS
4826
System.Object
4927
28+
The value to serialize. Multiple pipeline records are collected into one sequence.
29+
5030
.OUTPUTS
5131
System.String
5232
33+
The YAML 1.2-compatible text emitted for the input values.
34+
5335
.LINK
54-
https://github.com/PSModule/Yaml#serialize-powershell-values
36+
https://psmodule.io/Yaml/Functions/ConvertTo-Yaml/
5537
#>
5638
[CmdletBinding()]
5739
[OutputType([string])]
5840
param (
41+
# The value to serialize. Multiple pipeline records are collected into
42+
# a single top-level YAML sequence.
5943
[Parameter(Mandatory, Position = 0, ValueFromPipeline)]
6044
[AllowNull()]
6145
[object] $InputObject,
6246

47+
# Cap object-graph nesting depth so deep or hostile graphs can't exhaust
48+
# the stack.
49+
[Parameter()]
6350
[ValidateRange(1, 128)]
6451
[int] $Depth = 100,
6552

53+
# Cap the total number of traversed nodes to bound memory and time.
54+
[Parameter()]
6655
[ValidateRange(1, 2147483647)]
6756
[int] $MaxNodes = 100000,
6857

58+
# Cap the character count of any single emitted scalar.
59+
[Parameter()]
6960
[ValidateRange(1, 2147483647)]
7061
[int] $MaxScalarLength = 1048576,
7162

63+
# Number of spaces per block-indentation level in the emitted YAML.
64+
[Parameter()]
7265
[ValidateRange(2, 9)]
7366
[int] $Indent = 2,
7467

68+
# Emit an explicit `---` document-start marker ahead of the content.
69+
[Parameter()]
7570
[switch] $ExplicitDocumentStart,
7671

72+
# Emit enum names as strings instead of their underlying numeric values.
73+
[Parameter()]
7774
[switch] $EnumsAsStrings
7875
)
7976

‎src/functions/public/Export-Yaml.ps1‎

Lines changed: 5 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -13,56 +13,6 @@ function Export-Yaml {
1313
replaces or moves to the destination. Existing files are never
1414
truncated before serialization and writing succeed.
1515
16-
.PARAMETER InputObject
17-
A value to serialize. Multiple pipeline records become one YAML
18-
sequence. A directly supplied array is one input value.
19-
20-
.PARAMETER Path
21-
One literal FileSystem destination path. Wildcard characters are not
22-
expanded.
23-
24-
.PARAMETER Depth
25-
Maximum object-graph nesting depth. The default is 100.
26-
27-
.PARAMETER MaxNodes
28-
Maximum number of traversed nodes. The default is 100000.
29-
30-
.PARAMETER MaxScalarLength
31-
Maximum character count for one emitted scalar. The default is
32-
1048576.
33-
34-
.PARAMETER Indent
35-
Block indentation from 2 through 9 spaces. The default is 2.
36-
37-
.PARAMETER ExplicitDocumentStart
38-
Emits an explicit `---` document start marker.
39-
40-
.PARAMETER EnumsAsStrings
41-
Emits enum names as strings instead of underlying numeric values.
42-
43-
.PARAMETER Encoding
44-
Strict output encoding. utf8 omits a byte order mark; utf8BOM and the
45-
UTF-16 and UTF-32 encodings include their corresponding byte order mark.
46-
47-
.PARAMETER NewLine
48-
Line ending used for emitted YAML structure. The default is LF.
49-
50-
.PARAMETER NoFinalNewline
51-
Omits the final line ending. By default, exactly one is written.
52-
53-
.PARAMETER NoClobber
54-
Fails when the destination already exists.
55-
56-
.PARAMETER Force
57-
Permits atomic replacement of a read-only destination and preserves its
58-
read-only attribute. Force cannot be combined with NoClobber.
59-
60-
.PARAMETER CreateDirectory
61-
Creates missing parent directories after ShouldProcess approval.
62-
63-
.PARAMETER PassThru
64-
Writes the final FileInfo after a successful export.
65-
6616
.EXAMPLE
6717
$config | Export-Yaml -Path '.\config.yaml'
6818
@@ -81,14 +31,18 @@ function Export-Yaml {
8131
.INPUTS
8232
System.Object
8333
34+
The value to serialize. Multiple pipeline records are collected into one sequence.
35+
8436
.OUTPUTS
8537
System.IO.FileInfo
8638
39+
The destination file, returned only when PassThru is set.
40+
8741
.NOTES
8842
Only FileSystem provider destinations are supported.
8943
9044
.LINK
91-
https://github.com/PSModule/Yaml#export-yaml-files
45+
https://psmodule.io/Yaml/Functions/Export-Yaml/
9246
#>
9347
[OutputType([System.IO.FileInfo])]
9448
[CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'Medium')]

‎src/functions/public/Format-Yaml.ps1‎

Lines changed: 23 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -16,36 +16,6 @@ function Format-Yaml {
1616
Pipeline strings are joined with a line feed and parsed as one stream,
1717
matching ConvertFrom-Yaml.
1818
19-
.PARAMETER InputObject
20-
YAML text. Multiple pipeline records are joined with a line feed and
21-
parsed as one YAML stream.
22-
23-
.PARAMETER Indent
24-
Block indentation from 2 through 9 spaces. The default is 2.
25-
26-
.PARAMETER Depth
27-
Maximum YAML node nesting depth. The default is 100.
28-
29-
.PARAMETER MaxNodes
30-
Maximum number of YAML nodes in the stream. The default is 100000.
31-
32-
.PARAMETER MaxAliases
33-
Maximum number of alias nodes in the stream. The default is 1000.
34-
35-
.PARAMETER MaxScalarLength
36-
Maximum decoded character count for one scalar. The default is
37-
1048576.
38-
39-
.PARAMETER MaxTagLength
40-
Maximum expanded character count for one tag. The default is 1024.
41-
42-
.PARAMETER MaxTotalTagLength
43-
Maximum cumulative expanded tag characters. The default is 65536.
44-
45-
.PARAMETER MaxNumericLength
46-
Maximum digits in an implicitly or explicitly typed number. The
47-
default is 4096.
48-
4919
.EXAMPLE
5020
Get-Content -Path '.\config.yaml' | Format-Yaml
5121
@@ -60,40 +30,62 @@ function Format-Yaml {
6030
.INPUTS
6131
System.String[]
6232
33+
The YAML text to normalize. Multiple pipeline records are joined with a line feed.
34+
6335
.OUTPUTS
6436
System.String
6537
38+
The normalized YAML stream emitted from the representation graph.
39+
6640
.LINK
67-
https://github.com/PSModule/Yaml#format-yaml-streams
41+
https://psmodule.io/Yaml/Functions/Format-Yaml/
6842
#>
6943
[CmdletBinding()]
7044
[OutputType([string])]
7145
param (
46+
# The YAML text to normalize. Multiple pipeline records are joined with
47+
# a line feed and parsed as a single stream, matching ConvertFrom-Yaml.
7248
[Parameter(Mandatory, Position = 0, ValueFromPipeline)]
7349
[AllowEmptyString()]
7450
[string[]] $InputObject,
7551

52+
# Number of spaces per block-indentation level in the emitted YAML.
53+
[Parameter()]
7654
[ValidateRange(2, 9)]
7755
[int] $Indent = 2,
7856

57+
# Cap YAML node nesting depth so hostile input can't exhaust the stack.
58+
[Parameter()]
7959
[ValidateRange(1, 128)]
8060
[int] $Depth = 100,
8161

62+
# Cap the total node count to bound memory for a single stream.
63+
[Parameter()]
8264
[ValidateRange(1, 2147483647)]
8365
[int] $MaxNodes = 100000,
8466

67+
# Cap alias nodes to prevent alias-expansion amplification.
68+
[Parameter()]
8569
[ValidateRange(0, 2147483647)]
8670
[int] $MaxAliases = 1000,
8771

72+
# Cap decoded characters per scalar to bound per-node memory.
73+
[Parameter()]
8874
[ValidateRange(1, 2147483647)]
8975
[int] $MaxScalarLength = 1048576,
9076

77+
# Cap expanded characters for a single tag.
78+
[Parameter()]
9179
[ValidateRange(1, 1048576)]
9280
[int] $MaxTagLength = 1024,
9381

82+
# Cap cumulative expanded tag characters across the stream.
83+
[Parameter()]
9484
[ValidateRange(1, 2147483647)]
9585
[int] $MaxTotalTagLength = 65536,
9686

87+
# Cap the digit count of an implicitly or explicitly typed number.
88+
[Parameter()]
9789
[ValidateRange(1, 1048576)]
9890
[int] $MaxNumericLength = 4096
9991
)

0 commit comments

Comments
 (0)