Add full module scaffolding functions with documentation, strict parameter ordering, and consistent template generation

This commit updates and standardizes all scaffolding functions in the module template system. Each function now includes full comment‑based help, mandatory parameter ordering, UTF‑8 output, and consistent single‑quoted template here‑strings with placeholder replacement. The module generator now produces a complete, professional PowerShell module structure including manifest, loader, tests, analyzer settings, documentation scripts, build/publish scripts, and README generation.

Author: kael-sterling

NewModuleTemplate.psd1

@@ -20,6 +20,7 @@
         'New-DocumentationScripts',
         'New-ModuleChangelog',
         'New-ModuleFolders',
+        'New-ModuleLoader',
         'New-ModuleManifestFile',
         'New-ModuleReadme',
         'New-ModuleTemplate',

NewModuleTemplate.psm1

@@ -17,6 +17,7 @@ Export-ModuleMember -Function @(
     'New-DocumentationScripts',
     'New-ModuleChangelog',
     'New-ModuleFolders',
+    'New-ModuleLoader',
     'New-ModuleManifestFile',
     'New-ModuleReadme',
     'New-ModuleTemplate',

Public/Initialize-GitRepository.ps1

@@ -1,6 +1,35 @@
+<#
+.SYNOPSIS
+    Initializes a new Git repository inside a module folder.
+
+.DESCRIPTION
+    Creates a .gitignore file, initializes a Git repository, stages all files,
+    and performs an initial commit. This function is used by New-ModuleTemplate
+    when the -InitGit switch is provided.
+
+.PARAMETER BasePath
+    The root directory of the module where the Git repository should be created.
+    This must be the module's top-level folder (e.g., C:\Projects\MyModule).
+
+.EXAMPLE
+    Initialize-GitRepository -BasePath "C:\Projects\MyModule"
+
+.EXAMPLE
+    $root = "C:\Modules\Tools"
+    Initialize-GitRepository -BasePath $root
+
+.NOTES
+    - Requires Git to be installed and available in PATH.
+    - This function performs a commit with the message "Initial commit".
+#>
 function Initialize-GitRepository {
-    param([string]$BasePath)
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$BasePath
+    )
 
+    # Create a standard .gitignore file for PowerShell modules
     $gitignore = @'
 ## Build artifacts
 bin/
@@ -17,15 +46,17 @@ Docs/*.xml
 
 # Logs
 *.log
-
 '@
 
-    Set-Content -Path "$BasePath\.gitignore" -Value $gitignore
+    # Write .gitignore to the module root
+    Set-Content -Path "$BasePath\.gitignore" -Value $gitignore -Encoding UTF8
 
+    # Initialize the Git repository inside the module folder
     Push-Location $BasePath
     git init | Out-Null
     Pop-Location
 
+    # Stage all files and create the initial commit
     git -C $BasePath add . | Out-Null
     git -C $BasePath commit -m "Initial commit" | Out-Null
 }

Public/New-AnalyzerSettings.ps1

@@ -1,14 +1,53 @@
+<#
+.SYNOPSIS
+    Generates a PSScriptAnalyzer settings file for the module.
+
+.DESCRIPTION
+    Creates a PSScriptAnalyzer settings file inside the module's AnalyzerSettings
+    directory. The file defines rule severities and allows the module to enforce
+    consistent linting behavior across development environments and CI pipelines.
+
+.PARAMETER BasePath
+    The root directory of the module where the AnalyzerSettings folder exists.
+    This is typically the path returned by New-ModuleFolders.
+
+.EXAMPLE
+    New-AnalyzerSettings -BasePath "C:\Projects\MyModule"
+
+.EXAMPLE
+    $root = Join-Path $env:TEMP "TestModule"
+    New-AnalyzerSettings -BasePath $root
+
+.NOTES
+    This function is automatically invoked by New-ModuleTemplate.
+    The settings file created is named PSScriptAnalyzerSettings.psd1.
+#>
 function New-AnalyzerSettings {
-    param([string]$BasePath)
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [string]$BasePath
+    )
+
+    # Path to the AnalyzerSettings directory
+    $settingsDir = Join-Path $BasePath 'Analyzer'
+
+    # Ensure the directory exists (New-ModuleFolders normally creates it)
+    if (-not (Test-Path $settingsDir)) {
+        New-Item -ItemType Directory -Path $settingsDir -Force | Out-Null
+    }
 
+    # Default analyzer configuration
     $content = @'
 @{
     Severity = @{
         PSAvoidUsingWriteHost = 'Warning'
-        PSProvideCommentHelp = 'Information'
+        PSProvideCommentHelp  = 'Information'
     }
 }
 '@
 
-    Set-Content -Path "$BasePath\Analyzer\PSScriptAnalyzerSettings.psd1" -Value $content
+    # Write the settings file
+    $settingsPath = Join-Path $settingsDir 'PSScriptAnalyzerSettings.psd1'
+    Set-Content -Path $settingsPath -Value $content -Encoding UTF8
 }

Public/New-BuildScript.ps1

@@ -3,7 +3,29 @@
     Creates a build.ps1 script inside the generated module.
 
 .DESCRIPTION
-    The build script runs PSScriptAnalyzer, Pester tests, and updates PlatyPS documentation.
+    Generates a build script that performs common module maintenance tasks:
+    - Runs PSScriptAnalyzer using the module's analyzer settings
+    - Executes Pester tests
+    - Regenerates PlatyPS documentation
+    The script supports switches to skip individual steps.
+
+.PARAMETER BasePath
+    The root directory of the module where the Scripts folder will be created.
+
+.PARAMETER Name
+    The name of the module. Used to reference the module manifest and display
+    status messages inside the generated build script.
+
+.EXAMPLE
+    New-BuildScript -BasePath "C:\Projects\MyModule" -Name "MyModule"
+
+.EXAMPLE
+    $root = Join-Path $env:TEMP "TestModule"
+    New-BuildScript -BasePath $root -Name "TestModule"
+
+.NOTES
+    - The Analyzer folder is intentionally named "Analyzer".
+    - This script is automatically invoked by New-ModuleTemplate.
 #>
 function New-BuildScript {
     [CmdletBinding()]
@@ -15,6 +37,13 @@ function New-BuildScript {
         [string]$Name
     )
 
+    # Ensure the Scripts directory exists
+    $scriptsDir = Join-Path $BasePath 'Scripts'
+    if (-not (Test-Path $scriptsDir)) {
+        New-Item -ItemType Directory -Path $scriptsDir -Force | Out-Null
+    }
+
+    # Template for the build script
     $content = @'
 param(
     [switch]$SkipTests,
@@ -43,7 +72,10 @@ if (-not $SkipDocs) {
 Write-Host "Build complete."
 '@
 
+    # Replace placeholder with module name
     $content = $content.Replace('__MODULE__', $Name)
 
-    Set-Content -Path "$BasePath\Scripts\build.ps1" -Value $content
+    # Write the build script
+    $buildScriptPath = Join-Path $scriptsDir 'build.ps1'
+    Set-Content -Path $buildScriptPath -Value $content -Encoding UTF8 -Force
 }

Public/New-DocumentationScripts.ps1

@@ -1,17 +1,58 @@
+<#
+.SYNOPSIS
+    Creates a documentation update script for the module.
+
+.DESCRIPTION
+    Generates a PowerShell script that updates PlatyPS-based Markdown help
+    for the module. The script imports PlatyPS and calls Update-MarkdownHelp
+    using the module's manifest and Docs folder. This allows developers to
+    regenerate documentation after modifying public functions.
+
+.PARAMETER BasePath
+    The root directory of the module where the Scripts folder will be created.
+
+.PARAMETER Name
+    The name of the module. Used to reference the module manifest inside the
+    generated documentation update script.
+
+.EXAMPLE
+    New-DocumentationScripts -BasePath "C:\Projects\MyModule" -Name "MyModule"
+
+.EXAMPLE
+    $root = Join-Path $env:TEMP "TestModule"
+    New-DocumentationScripts -BasePath $root -Name "TestModule"
+
+.NOTES
+    - The generated script is named Update-ModuleDocumentation.ps1.
+    - PlatyPS must be installed for the script to run successfully.
+#>
 function New-DocumentationScripts {
+    [CmdletBinding()]
     param(
+        [Parameter(Mandatory)]
         [string]$BasePath,
+
+        [Parameter(Mandatory)]
         [string]$Name
     )
 
+    # Ensure the Scripts directory exists
+    $scriptsDir = Join-Path $BasePath 'Scripts'
+    if (-not (Test-Path $scriptsDir)) {
+        New-Item -ItemType Directory -Path $scriptsDir -Force | Out-Null
+    }
+
+    # Template for the documentation update script
     $content = @'
 Import-Module PlatyPS
 
-Update-MarkdownHelp -Module "$PSScriptRoot\..\__MODULE_NAME__.psd1" -OutputFolder "$PSScriptRoot\Docs" -Force
+Update-MarkdownHelp -Module "$PSScriptRoot\..\__MODULE_NAME__.psd1" -OutputFolder "$PSScriptRoot\..\Docs" -Force
 '@
 
-    $content = $content.Replace('__MODULE_NAME__', "$Name")
-    # $content = $content.Replace('__DOCS_PATH__', "$BasePath\Docs")
+    # Replace placeholder with module name
+    $content = $content.Replace('__MODULE_NAME__', $Name)
 
-    Set-Content -Path "$BasePath\Scripts\Update-ModuleDocumentation.ps1" -Value $content
+    # Write the documentation update script
+    $docScriptPath = Join-Path $scriptsDir 'Update-ModuleDocumentation.ps1'
+    Set-Content -Path $docScriptPath -Value $content -Encoding UTF8
 }

Public/New-ModuleChangelog.ps1

@@ -1,8 +1,40 @@
+<#
+.SYNOPSIS
+    Creates or updates a CHANGELOG.md file for the module.
+
+.DESCRIPTION
+    Generates a Markdown changelog file following the "Keep a Changelog" format
+    and Semantic Versioning guidelines. The function writes a new changelog
+    entry using the provided version and notes. If the file does not exist,
+    it is created. If it exists, the new entry is appended.
+
+.PARAMETER BasePath
+    The root directory of the module where CHANGELOG.md will be created.
+
+.PARAMETER Version
+    The version number associated with the changelog entry.
+    Defaults to "1.0.0".
+
+.PARAMETER Notes
+    A description of the changes included in this version.
+    Defaults to "Initial release."
+
+.EXAMPLE
+    New-ModuleChangelog -BasePath "C:\Projects\MyModule" -Version "1.2.0" -Notes "Added new API endpoints"
+
+.EXAMPLE
+    $root = Join-Path $env:TEMP "TestModule"
+    New-ModuleChangelog -BasePath $root -Version "0.1.0" -Notes "Prototype scaffolding"
+
+.NOTES
+    - This function is typically invoked by New-ModuleTemplate.
+    - The changelog format follows https://keepachangelog.com/.
+#>
 function New-ModuleChangelog {
     [CmdletBinding()]
     param(
         [Parameter(Mandatory)]
-        [string]$Path,
+        [string]$BasePath,
 
         [Parameter()]
         [string]$Version = "1.0.0",
@@ -11,14 +43,15 @@ function New-ModuleChangelog {
         [string]$Notes = "Initial release."
     )
 
-    # Ensure the path exists
-    if (-not (Test-Path $Path)) {
-        throw "The path '$Path' does not exist."
+    # Ensure the module root exists
+    if (-not (Test-Path $BasePath)) {
+        throw "The path '$BasePath' does not exist."
     }
 
-    $changelogPath = Join-Path $Path "CHANGELOG.md"
+    # Path to the changelog file
+    $changelogPath = Join-Path $BasePath "CHANGELOG.md"
 
-    # Build content
+    # Build the changelog entry
     $date = (Get-Date).ToString("yyyy-MM-dd")
 
     $content = @"
@@ -34,7 +67,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 "@
 
-    # Write file
+    # Write the changelog file (overwrite or create)
     Set-Content -Path $changelogPath -Value $content -Encoding UTF8
 
     # Return the path for convenience

Public/New-ModuleFolders.ps1

@@ -1,21 +1,54 @@
+<#
+.SYNOPSIS
+    Creates the folder structure for a new PowerShell module.
+
+.DESCRIPTION
+    Generates the standard directory layout used by your module scaffolding
+    system. This includes the Public, Private, Tests, Docs, Analyzer, and
+    Scripts directories. The function returns the full path to the module's
+    root folder.
+
+.PARAMETER BasePath
+    The directory where the module folder will be created. The module root
+    becomes <BasePath>\<Name>.
+
+.PARAMETER Name
+    The name of the module. This becomes the root folder name and is used
+    throughout the scaffolding process.
+
+.EXAMPLE
+    New-ModuleFolders -BasePath "C:\Projects" -Name "MyModule"
+
+.EXAMPLE
+    $root = Join-Path $env:TEMP "TestModule"
+    New-ModuleFolders -BasePath $root -Name "Tools"
+
+.NOTES
+    - This function is invoked internally by New-ModuleTemplate.
+    - The folder names are intentionally kept as: Public, Private, Tests,
+      Docs, Analyzer, Scripts.
+#>
 function New-ModuleFolders {
     [CmdletBinding()]
     param(
         [Parameter(Mandatory)]
-        [string]$Name,
+        [string]$Path,
 
         [Parameter(Mandatory)]
-        [string]$Path
+        [string]$Name
     )
 
-    # Base module path: <Path>\<Name>
-    $base = Join-Path $Path $Name
-    New-Item -ItemType Directory -Path $base -Force | Out-Null
+    # Build the module root path: <BasePath>\<Name>
+    $moduleRoot = Join-Path $Path $Name
+
+    # Create the root folder
+    New-Item -ItemType Directory -Path $moduleRoot -Force | Out-Null
 
-    # Standard module folder structure
+    # Create the standard module subfolders
     foreach ($folder in 'Public', 'Private', 'Tests', 'Docs', 'Analyzer', 'Scripts') {
-        New-Item -ItemType Directory -Path (Join-Path $base $folder) -Force | Out-Null
+        New-Item -ItemType Directory -Path (Join-Path $moduleRoot $folder) -Force | Out-Null
     }
 
-    return $base
+    # Return the module root path for chaining
+    return $moduleRoot
 }