Fix comment-based help formatting and enhance QA tests for example code blocks

Author: johlju

CHANGELOG.md

@@ -184,6 +184,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
+- `New-SqlDscFileGroup`
+  - Fixed comment-based help example formatting by moving inline comment
+    to the description text.
+- QA Tests
+  - Added new test to detect comments within multi-line example code blocks
+    in comment-based help. Comments in the code portion of `.EXAMPLE` blocks
+    cause PlatyPS documentation generation to fail with "Expect Heading" errors.
 - Unit Tests
   - Fixed PowerShell class type identity issues that caused "Cannot convert
     'Type' to 'Type'" errors when running multiple test files in the same

source/Public/New-SqlDscFileGroup.ps1

@@ -56,10 +56,10 @@
 
     .EXAMPLE
         $fileGroup = New-SqlDscFileGroup -Name 'MyFileGroup'
-        # Later add to database
         Add-SqlDscFileGroup -Database $database -FileGroup $fileGroup
 
-        Creates a standalone FileGroup that can be added to a Database later.
+        Creates a standalone FileGroup that can be added to a Database later
+        using Add-SqlDscFileGroup.
 
     .EXAMPLE
         $fileGroupSpec = New-SqlDscFileGroup -Name 'PRIMARY' -AsSpec

source/Public/Request-SqlDscRSDatabaseRightsScript.ps1

@@ -43,11 +43,8 @@
         database for the Reporting Services service account.
 
     .EXAMPLE
-        # Get the Reporting Services service account name
         $rsService = Get-SqlDscManagedComputerService -ServiceType 'ReportingServices'
         $serviceAccount = $rsService.ServiceAccount
-
-        # Generate and execute the rights script
         $config = Get-SqlDscRSConfiguration -InstanceName 'SSRS'
         $script = $config | Request-SqlDscRSDatabaseRightsScript -DatabaseName 'ReportServer' -UserName $serviceAccount
         Invoke-SqlDscQuery -ServerName 'localhost' -InstanceName 'RSDB' -DatabaseName 'master' -Query $script -Force

source/Public/Request-SqlDscRSDatabaseScript.ps1

@@ -36,7 +36,7 @@
 
     .EXAMPLE
         $config = Get-SqlDscRSConfiguration -InstanceName 'SSRS'
-        $script = Request-SqlDscRSDatabaseScript -Configuration $config -DatabaseName 'ReportServer'
+        $script = $config | Request-SqlDscRSDatabaseScript -DatabaseName 'ReportServer'
         Invoke-SqlDscQuery -ServerName 'localhost' -InstanceName 'RSDB' -DatabaseName 'master' -Query $script -Force
 
         Generates the database creation script and executes it on the RSDB

tests/QA/module.tests.ps1

@@ -238,6 +238,55 @@ Describe 'Comment-based help structure' -Tags 'helpQuality' {
                 $invalidDirectives | Should -BeNullOrEmpty -Because ('invalid help directives found that will break help parsing: {0}' -f ($invalidDirectives -join ', '))
             }
         }
+
+        It 'Should not have comments within multi-line example code blocks for <Name>' {
+            <#
+                PlatyPS expects .EXAMPLE blocks to have: code (no comments) → blank line → description.
+                Comments (lines starting with #) within the code portion cause "Expect Heading" errors
+                during documentation generation because PlatyPS interprets them incorrectly.
+            #>
+            if ($scriptFileRawContent -match '(?s)<#(.*?)#>')
+            {
+                $helpBlock = $Matches[1]
+
+                # Find all .EXAMPLE blocks
+                $exampleMatches = [regex]::Matches($helpBlock, '(?s)\.EXAMPLE\s*\r?\n(.*?)(?=\r?\n\s*\.(?:EXAMPLE|PARAMETER|SYNOPSIS|DESCRIPTION|INPUTS|OUTPUTS|NOTES|LINK|COMPONENT|ROLE|FUNCTIONALITY)|$)')
+
+                $examplesWithComments = @()
+
+                foreach ($exampleMatch in $exampleMatches)
+                {
+                    $exampleContent = $exampleMatch.Groups[1].Value
+                    $exampleLines = $exampleContent -split '\r?\n'
+
+                    # Find where the description starts (first line after a blank line that follows code)
+                    $inCodeBlock = $true
+                    $foundBlankLine = $false
+
+                    foreach ($line in $exampleLines)
+                    {
+                        $trimmedLine = $line.Trim()
+
+                        if ($inCodeBlock)
+                        {
+                            if ([string]::IsNullOrEmpty($trimmedLine))
+                            {
+                                # Blank line - marks end of code block
+                                $foundBlankLine = $true
+                                $inCodeBlock = $false
+                            }
+                            elseif ($trimmedLine -match '^#(?!region|endregion)')
+                            {
+                                # Found a comment in the code block (excluding #region/#endregion)
+                                $examplesWithComments += $trimmedLine
+                            }
+                        }
+                    }
+                }
+
+                $examplesWithComments | Should -BeNullOrEmpty -Because ('comments within example code blocks break PlatyPS documentation generation: {0}' -f ($examplesWithComments -join ', '))
+            }
+        }
     }
 }