feat(docs): add synopsis and parameter descriptions to functions for better documentation

Author: MariusStorhaug

.github/linters/.powershell-psscriptanalyzer.psd1

@@ -50,6 +50,7 @@
         }
     }
     ExcludeRules = @(
+        'PSAvoidUsingWriteHost',        # Write-Host is acceptable in guidance scripts.
         'PSMissingModuleManifestField', # This rule is not applicable until the module is built.
         'PSUseToExportFieldsInManifest'
     )

guidance/Caller.ps1

@@ -1,4 +1,8 @@
 function Invoke-Function4 {
+    <#
+        .SYNOPSIS
+        Demonstrates caller detection using Get-PSCallStack.
+    #>
     [CmdletBinding()]
     param()
     'In: ' + $MyInvocation.InvocationName
@@ -7,6 +11,10 @@
 }
 
 function Invoke-Function3 {
+    <#
+        .SYNOPSIS
+        Demonstrates nested caller detection at depth 3.
+    #>
     [CmdletBinding()]
     param()
     'In: ' + $MyInvocation.InvocationName
@@ -16,6 +24,10 @@ function Invoke-Function3 {
 }
 
 function Invoke-Function2 {
+    <#
+        .SYNOPSIS
+        Demonstrates nested caller detection at depth 2.
+    #>
     [CmdletBinding()]
     param()
     'In: ' + $MyInvocation.InvocationName
@@ -25,6 +37,10 @@ function Invoke-Function2 {
 }
 
 function Invoke-Function1 {
+    <#
+        .SYNOPSIS
+        Entry point demonstrating caller detection through the call stack.
+    #>
     [CmdletBinding()]
     param()
     'In: ' + $MyInvocation.InvocationName

guidance/Loops.ps1

@@ -9,6 +9,10 @@ $RepeatCount = 10000
 
 'Wrapped in a function = {0}ms' -f (Measure-Command -Expression {
         function Get-RandNum_Core {
+            <#
+                .SYNOPSIS
+                Gets a random number using a shared Random instance.
+            #>
             param ($ranGen)
             $ranGen.Next()
         }
@@ -20,6 +24,10 @@ $RepeatCount = 10000
 
 'For-loop in a function = {0}ms' -f (Measure-Command -Expression {
         function Get-RandNum_All {
+            <#
+                .SYNOPSIS
+                Gets random numbers in a loop using a shared Random instance.
+            #>
             param ($ranGen)
             for ($i = 0; $i -lt $RepeatCount; $i++) {
                 $Null = $ranGen.Next()

guidance/PSCallStack.ps1

@@ -1,11 +1,19 @@
 function Invoke-Function4 {
+    <#
+        .SYNOPSIS
+        Demonstrates Get-PSCallStack at the deepest call level.
+    #>
     [CmdletBinding()]
     param()
     'In: ' + $MyInvocation.InvocationName
     Get-PSCallStack
 }
 
 function Invoke-Function3 {
+    <#
+        .SYNOPSIS
+        Demonstrates Get-PSCallStack at call depth 3.
+    #>
     [CmdletBinding()]
     param()
     'In: ' + $MyInvocation.InvocationName
@@ -14,6 +22,10 @@ function Invoke-Function3 {
 }
 
 function Invoke-Function2 {
+    <#
+        .SYNOPSIS
+        Demonstrates Get-PSCallStack at call depth 2.
+    #>
     [CmdletBinding()]
     param()
     'In: ' + $MyInvocation.InvocationName
@@ -22,6 +34,10 @@ function Invoke-Function2 {
 }
 
 function Invoke-Function1 {
+    <#
+        .SYNOPSIS
+        Entry point demonstrating Get-PSCallStack through nested calls.
+    #>
     [CmdletBinding()]
     param()
     "In: " + $MyInvocation.InvocationName

guidance/PSCmdlet.ps1

@@ -1,11 +1,19 @@
 function Invoke-Function4 {
+    <#
+        .SYNOPSIS
+        Demonstrates PSCmdlet variable at the deepest call level.
+    #>
     [CmdletBinding()]
     param()
     '4: ' + $MyInvocation.InvocationName
     $PSCmdlet | ConvertTo-Json
 }
 
 function Invoke-Function3 {
+    <#
+        .SYNOPSIS
+        Demonstrates PSCmdlet variable at call depth 3.
+    #>
     [CmdletBinding()]
     param()
     '3: ' + $MyInvocation.InvocationName
@@ -14,6 +22,10 @@ function Invoke-Function3 {
 }
 
 function Invoke-Function2 {
+    <#
+        .SYNOPSIS
+        Demonstrates PSCmdlet variable at call depth 2.
+    #>
     [CmdletBinding()]
     param()
     '2: ' + $MyInvocation.InvocationName
@@ -22,6 +34,10 @@ function Invoke-Function2 {
 }
 
 function Invoke-Function1 {
+    <#
+        .SYNOPSIS
+        Entry point demonstrating PSCmdlet variable through nested calls.
+    #>
     [CmdletBinding()]
     param()
     '1: ' + $MyInvocation.InvocationName

guidance/PipelineExecution.ps1

@@ -1,5 +1,13 @@
 function Set-DefaultParameterValue {
-    [CmdletBinding()]
+    <#
+        .SYNOPSIS
+        Sets a default parameter value with a simulated delay.
+
+        .PARAMETER Parameter
+        The parameter value to set.
+    #>
+    [CmdletBinding(SupportsShouldProcess)]
+    [OutputType([string])]
     param (
         [string]$Parameter = 'Default-Parameter'
     )
@@ -9,6 +17,16 @@
 }
 
 function Step-One {
+    <#
+        .SYNOPSIS
+        First pipeline step that multiplies input by 10.
+
+        .PARAMETER InputNumber
+        The number to process.
+
+        .PARAMETER Parameter
+        Optional parameter with a default value.
+    #>
     [CmdletBinding()]
     param (
         [Parameter(ValueFromPipeline = $true)]
@@ -38,6 +56,16 @@ function Step-One {
 }
 
 function Step-Two {
+    <#
+        .SYNOPSIS
+        Second pipeline step that adds 5 to input.
+
+        .PARAMETER InputNumber
+        The number to process.
+
+        .PARAMETER Parameter
+        Optional parameter with a default value.
+    #>
     [CmdletBinding()]
     param (
         [Parameter(ValueFromPipeline = $true)]
@@ -66,6 +94,16 @@ function Step-Two {
 }
 
 function Step-Three {
+    <#
+        .SYNOPSIS
+        Third pipeline step that subtracts 2 from input.
+
+        .PARAMETER InputNumber
+        The number to process.
+
+        .PARAMETER Parameter
+        Optional parameter with a default value.
+    #>
     [CmdletBinding()]
     param (
         [Parameter(ValueFromPipeline = $true)]

guidance/Read-File.ps1

@@ -1,5 +1,15 @@
 # Function to simulate processing each line
 function Test-LineProcessing {
+    <#
+        .SYNOPSIS
+        Simulates processing a single line of text.
+
+        .DESCRIPTION
+        Returns whether the input text has a length greater than zero.
+
+        .PARAMETER InputText
+        The text line to process.
+    #>
     param([string]$InputText)
     # Simulate some work by creating a simple string operation
     $InputText.Length > 0