Native help and action descriptions state framework behavior directly

.github/actions/Build-PSModule/action.yml

@@ -1,27 +1,27 @@
 name: Build-PSModule
-description: Build a PowerShell module to the PowerShell Gallery.
+description: Build a PowerShell module for the PowerShell Gallery.
 author: PSModule
 
 inputs:
   Name:
     description: Name of the module to build. Defaults to the repository name.
     required: false
   OutputFolder:
-    description: Path to the folder where the built module is outputted.
+    description: Path to the folder for the built module.
     required: false
     default: '.PSModule/module'
   Version:
     description: Module version to stamp into the manifest.
     required: true
   Prerelease:
-    description: Prerelease tag to stamp into the manifest's `PrivateData.PSData.Prerelease`. When empty, no prerelease tag is written.
+    description: Prerelease tag for the manifest's `PrivateData.PSData.Prerelease`. An empty value omits the prerelease tag.
     required: false
   ArtifactName:
     description: Name of the artifact to upload.
     required: false
     default: module
   WorkingDirectory:
-    description: The working directory where the script will run from.
+    description: Working directory for the script.
     required: false
     default: '.'
 

.github/actions/Build-PSModule/src/helpers/Build-PSModule.ps1

@@ -1,10 +1,10 @@
 function Build-PSModule {
     <#
         .SYNOPSIS
-        Builds a module.
+        Build a PowerShell module from source files.
 
         .DESCRIPTION
-        Builds a module.
+        Build-PSModule copies the source files, creates the manifest, and combines the scripts into the root module.
     #>
     [OutputType([void])]
     [CmdletBinding()]
@@ -21,19 +21,19 @@
         [Parameter(Mandatory)]
         [string] $ModuleName,
 
-        # Path to the folder where the modules are located.
+        # Path to the module source folder.
         [Parameter(Mandatory)]
         [string] $ModuleSourceFolderPath,
 
-        # Path to the folder where the built modules are outputted.
+        # Path to the folder for the built module.
         [Parameter(Mandatory)]
         [string] $ModuleOutputFolderPath,
 
         # Module version to stamp into the manifest.
         [Parameter(Mandatory)]
         [string] $ModuleVersion,
 
-        # Prerelease tag to stamp into the manifest. When empty, no prerelease tag is written.
+        # Prerelease tag for the manifest. An empty value omits the prerelease tag.
         [Parameter()]
         [string] $ModulePrerelease
     )

.github/actions/Build-PSModule/src/helpers/Build/Add-ContentFromItem.ps1

@@ -4,7 +4,7 @@ function Add-ContentFromItem {
         Add the content of a folder or file to the root module file.
 
         .DESCRIPTION
-        This function will add the content of a folder or file to the root module file.
+        Add-ContentFromItem adds the content of a folder or file to the root module file.
 
         .EXAMPLE
         Add-ContentFromItem -Path 'C:\MyModule\src\MyModule' -RootModuleFilePath 'C:\MyModule\src\MyModule.psm1' -RootPath 'C:\MyModule\src'

.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleBase.ps1

@@ -1,11 +1,11 @@
 function Build-PSModuleBase {
     <#
     .SYNOPSIS
-    Compiles the base module files.
+    Build the base module files.
 
     .DESCRIPTION
-    This function will compile the base module files.
-    It will copy the source files to the output folder and remove the files that are not needed.
+    Build-PSModuleBase copies source files to the output folder.
+    It creates an empty root module file.
 
     .EXAMPLE
     Build-PSModuleBase -SourceFolderPath 'C:\MyModule\src\MyModule' -OutputFolderPath 'C:\MyModule\build\MyModule'
@@ -24,11 +24,11 @@
         [Parameter(Mandatory)]
         [string] $ModuleName,
 
-        # Path to the folder where the module source code is located.
+        # Path to the module source folder.
         [Parameter(Mandatory)]
         [System.IO.DirectoryInfo] $ModuleSourceFolder,
 
-        # Path to the folder where the built modules are outputted.
+        # Path to the folder for the built module.
         [Parameter(Mandatory)]
         [System.IO.DirectoryInfo] $ModuleOutputFolder
     )

.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleManifest.ps1

@@ -1,11 +1,10 @@
 function Build-PSModuleManifest {
     <#
     .SYNOPSIS
-    Compiles the module manifest.
+    Build the module manifest.
 
     .DESCRIPTION
-    This function will compile the module manifest.
-    It will generate the module manifest file and copy it to the output folder.
+    Build-PSModuleManifest creates the module manifest in the output folder.
 
     .EXAMPLE
     Build-PSModuleManifest -SourceFolderPath 'C:\MyModule\src\MyModule' -OutputFolderPath 'C:\MyModule\build\MyModule'
@@ -28,7 +27,7 @@
         [Parameter(Mandatory)]
         [string] $ModuleName,
 
-        # Folder where the built module is outputted. '.PSModule/module/MyModule'
+        # Folder for the built module files. '.PSModule/module/MyModule'
         [Parameter(Mandatory)]
         [System.IO.DirectoryInfo] $ModuleOutputFolder,
 

.github/actions/Build-PSModule/src/helpers/Build/Build-PSModuleRootModule.ps1

@@ -1,30 +1,29 @@
 function Build-PSModuleRootModule {
     <#
         .SYNOPSIS
-        Compiles the module root module files.
+        Build the root module file from source scripts.
 
         .DESCRIPTION
-        This function will compile the modules root module from source files.
-        It will copy the source files to the output folder and start compiling the module.
-        During compilation, the source files are added to the root module file in the following order:
+        Build-PSModuleRootModule combines source scripts in the output folder into the root module file.
+        It adds content in this order:
 
-        1. Module header from header.ps1 file. Usually to suppress code analysis warnings/errors and to add [CmdletBinding()] to the module.
-        2. Data loader is added if data files are available.
-        3. Combines *.ps1 files from the following folders in alphabetical order from each folder:
+        1. The header.ps1 module header, which can suppress code analysis warnings and errors or add [CmdletBinding()].
+        2. A data loader, if data files are available.
+        3. The *.ps1 files from these folders, in alphabetical order within each folder:
             1. init
             2. classes/private
             3. classes/public
             4. functions/private
             5. functions/public
             6. variables/private
             7. variables/public
-            8. Any remaining *.ps1 on module root.
-        4. Adds a class loader for classes found in the classes/public folder.
-        5. Export-ModuleMember by using the functions, cmdlets, variables and aliases found in the source files.
-            - `Functions` will only contain functions that are from the `functions/public` folder.
+            8. Any remaining *.ps1 files in the module root.
+        4. A class loader for classes in the classes/public folder.
+        5. An Export-ModuleMember call with the functions, cmdlets, variables, and aliases from the source files.
+            - `Functions` contains only functions from the `functions/public` folder.
             - `Cmdlets` will only contain cmdlets that are from the `cmdlets/public` folder.
-            - `Variables` will only contain variables that are from the `variables/public` folder.
-            - `Aliases` will only contain aliases that are from the functions from the `functions/public` folder.
+            - `Variables` contains only variables from the `variables/public` folder.
+            - `Aliases` contains only aliases from functions in the `functions/public` folder.
 
         .EXAMPLE
         Build-PSModuleRootModule -SourceFolderPath 'C:\MyModule\src\MyModule' -OutputFolderPath 'C:\MyModule\build\MyModule'
@@ -43,7 +42,7 @@
         [Parameter(Mandatory)]
         [string] $ModuleName,
 
-        # Folder where the built module is outputted. '.PSModule/module/MyModule'
+        # Folder for the built module files. '.PSModule/module/MyModule'
         [Parameter(Mandatory)]
         [System.IO.DirectoryInfo] $ModuleOutputFolder
     )

.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleAliasesToExport.ps1

@@ -1,10 +1,10 @@
 function Get-PSModuleAliasesToExport {
     <#
         .SYNOPSIS
-        Gets the aliases to export from the module manifest.
+        Get the aliases to export from the module manifest.
 
         .DESCRIPTION
-        This function will get the aliases to export from the module manifest.
+        Get-PSModuleAliasesToExport reads AliasesToExport from the module manifest.
 
         .EXAMPLE
         Get-PSModuleAliasesToExport -SourceFolderPath 'C:\MyModule\src\MyModule'
@@ -13,7 +13,7 @@
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Scope = 'Function', Justification = 'Want to just write to the console, not the pipeline.')]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidLongLines', '', Scope = 'Function', Justification = 'Contains long links.')]
     param(
-        # Path to the folder where the module source code is located.
+        # Path to the module source folder.
         [Parameter(Mandatory)]
         [string] $SourceFolderPath
     )

.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleClassesToExport.ps1

@@ -1,10 +1,10 @@
 function Get-PSModuleClassesToExport {
     <#
         .SYNOPSIS
-        Gets the classes to export from the module source code.
+        Get the classes and enums to export from the module source code.
 
         .DESCRIPTION
-        This function will get the classes to export from the module source code.
+        Get-PSModuleClassesToExport finds class and enum declarations in source files.
 
         .EXAMPLE
         Get-PSModuleClassesToExport -SourceFolderPath 'C:\MyModule\src\MyModule'

.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleCmdletsToExport.ps1

@@ -1,10 +1,10 @@
 function Get-PSModuleCmdletsToExport {
     <#
         .SYNOPSIS
-        Gets the cmdlets to export from the module manifest.
+        Get the cmdlets to export from the module manifest.
 
         .DESCRIPTION
-        This function will get the cmdlets to export from the module manifest.
+        Get-PSModuleCmdletsToExport reads CmdletsToExport from the module manifest.
 
         .EXAMPLE
         Get-PSModuleCmdletsToExport -SourceFolderPath 'C:\MyModule\src\MyModule'
@@ -13,7 +13,7 @@
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidUsingWriteHost', '', Scope = 'Function', Justification = 'Want to just write to the console, not the pipeline.')]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidLongLines', '', Scope = 'Function', Justification = 'Contains long links.')]
     param(
-        # Path to the folder where the module source code is located.
+        # Path to the module source folder.
         [Parameter(Mandatory)]
         [string] $SourceFolderPath
     )

.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleFunctionsToExport.ps1

@@ -1,10 +1,10 @@
 function Get-PSModuleFunctionsToExport {
     <#
         .SYNOPSIS
-        Gets the functions to export from the module manifest.
+        Get the functions and filters to export from the module source code.
 
         .DESCRIPTION
-        This function will get the functions to export from the module manifest.
+        Get-PSModuleFunctionsToExport reads public source files to identify the functions and filters to export.
 
         .EXAMPLE
         Get-PSModuleFunctionsToExport -SourceFolderPath 'C:\MyModule\src\MyModule'
@@ -14,7 +14,7 @@
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSAvoidLongLines', '', Scope = 'Function', Justification = 'Contains long links.')]
     [OutputType([array])]
     param(
-        # Path to the folder where the module source code is located.
+        # Path to the module source folder.
         [Parameter(Mandatory)]
         [string] $SourceFolderPath
     )

.github/actions/Build-PSModule/src/helpers/Build/Get-PSModuleVariablesToExport.ps1

@@ -1,10 +1,10 @@
 function Get-PSModuleVariablesToExport {
     <#
         .SYNOPSIS
-        Gets the variables to export from the module manifest.
+        Get the variables to export from the module source code.
 
         .DESCRIPTION
-        This function will get the variables to export from the module manifest.
+        Get-PSModuleVariablesToExport reads root-level assignments in public variable files.
 
         .EXAMPLE
         Get-PSModuleVariablesToExport -SourceFolderPath 'C:\MyModule\src\MyModule'
@@ -17,7 +17,7 @@
     [OutputType([Collections.Generic.List[string]])]
     [CmdletBinding()]
     param(
-        # Path to the folder where the module source code is located.
+        # Path to the module source folder.
         [Parameter(Mandatory)]
         [string] $SourceFolderPath
     )

.github/actions/Build-PSModule/src/helpers/Build/Get-RootLevelVariables.ps1

@@ -1,19 +1,19 @@
 function Get-RootLevelVariable {
     <#
         .SYNOPSIS
-        Get the root-level variables in a ast.
+        Get the root-level variables in an AST.
 
         .EXAMPLE
         Get-RootLevelVariable -Ast $ast
     #>
     [CmdletBinding()]
     param (
-        # The Abstract Syntax Tree (AST) to analyze
+        # The abstract syntax tree (AST) to analyze.
         [System.Management.Automation.Language.ScriptBlockAst]$Ast
     )
     # Iterate over the top-level statements in the AST
     foreach ($statement in $Ast.EndBlock.Statements) {
-        # Check if the statement is an assignment statement
+        # Return only variables from root-level assignments.
         if ($statement -is [System.Management.Automation.Language.AssignmentStatementAst]) {
             # Get the variable name, removing the scope prefix
             $statement.Left.VariablePath.UserPath -replace '.*:'

.github/actions/Build-PSModule/src/helpers/Build/Update-PSModuleManifestAliasesToExport.ps1

@@ -1,7 +1,7 @@
 function Update-PSModuleManifestAliasesToExport {
     <#
     .SYNOPSIS
-    Updates the aliases to export in the module manifest.
+    Update the aliases to export in the module manifest.
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '', Scope = 'Function',
@@ -21,11 +21,11 @@
         [Parameter(Mandatory)]
         [string] $ModuleName,
 
-        # Path to the folder where the module source code is located.
+        # Path to the module source folder.
         [Parameter(Mandatory)]
         [System.IO.DirectoryInfo] $ModuleSourceFolder,
 
-        # Path to the folder where the built modules are outputted.
+        # Path to the folder for the built module.
         [Parameter(Mandatory)]
         [System.IO.DirectoryInfo] $ModuleOutputFolder
     )
@@ -40,7 +40,7 @@
             return
         }
 
-        # Get all child items in the module source folder of a powershell file type
+        # Find PowerShell files in the public functions folder.
         $files = Get-ChildItem -Path $publicFunctionsPath -Recurse -File -Include '*.ps1', '*.psm1' | Select-Object -ExpandProperty FullName
 
         # Initialize an array to store all found aliases

.github/actions/Build-ZensicalSite/action.yml

@@ -1,5 +1,5 @@
 name: Build-ZensicalSite
-description: Build Zensical site output and normalize output folder.
+description: Build a Zensical site in the framework artifact directory.
 
 inputs:
   WorkingDirectory:

.github/actions/Build-ZensicalSite/src/main.ps1

@@ -2,11 +2,11 @@
 
 <#
     .SYNOPSIS
-    Builds the Zensical site under the framework artifact directory.
+    Build the Zensical site in the framework artifact directory.
 
     .DESCRIPTION
-    Runs zensical build from .PSModule/site. The generated site remains at
-    <WorkingDirectory>/.PSModule/site/_site for downstream workflow steps.
+    The script runs zensical build from .PSModule/site.
+    The site remains at <WorkingDirectory>/.PSModule/site/_site for later workflow steps.
 
     .EXAMPLE
     ./main.ps1 -WorkingDirectory '.'

.github/actions/Document-PSModule/action.yml

@@ -7,11 +7,11 @@ inputs:
     description: Name of the module to process.
     required: false
   ShowSummaryOnSuccess:
-    description: Show GitHub Step Summary even when all commands succeed.
+    description: Show the GitHub step summary even when all commands succeed.
     required: false
     default: 'false'
   WorkingDirectory:
-    description: The working directory where the script will run from.
+    description: Working directory for the script.
     required: false
     default: '.'