Fix New-MarkdownHelp to generate CommonParameters as required PowerShell/platyPS/#223 PowerShell/platyPS/#253 (#323)

Author: BernieWhite

CHANGELOG.md

@@ -6,6 +6,7 @@ CHANGELOG
 * Clean up trailing whitespace during markdown generation [#225](https://github.com/PowerShell/platyPS/issues/225)
 * Preserve line breaks after headers when Update-MarkdownHelp is used [#319](https://github.com/PowerShell/platyPS/issues/319)
 * MAML generation now pads example titles with dash (-) to improve readability [#119](https://github.com/PowerShell/platyPS/issues/119)
+* Fixed issue with New-MarkdownHelp preventing CommonParameter being added for advanced functions and workflows [#223](https://github.com/PowerShell/platyPS/issues/223) [#253](https://github.com/PowerShell/platyPS/issues/253)
 
 ## 0.8.3
 

src/Markdown.MAML/Renderer/Markdownv2Renderer.cs

@@ -181,7 +181,8 @@ private void AddParameters(MamlCommand command)
                 AddWorkflowParameters();
             }
 
-            if (command.SupportCommonParameters)
+            // Workflows always support CommonParameters
+            if (command.SupportCommonParameters || command.IsWorkflow)
             {
                 AddCommonParameters();
             }

src/platyPS/platyPS.psm1

@@ -2057,7 +2057,7 @@ function GetMamlObject
         {
             Write-Verbose ("`tProcessing: " + $Command.Name)
             $Help = Get-Help $Command.Name
-            # yeild
+            # yield
             ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UsePlaceholderForSynopsis:(CommandHasAutogeneratedSynopsis $Help)  -UseFullTypeName:$UseFullTypeName
         }
     }
@@ -2078,7 +2078,7 @@ function GetMamlObject
                 HelpFile = (Split-Path $MamlFile -Leaf)
             }
 
-            # yeild
+            # yield
             ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UseHelpForParametersMetadata  -UseFullTypeName:$UseFullTypeName
         }
     }
@@ -2616,18 +2616,15 @@ function ConvertPsObjectsToMamlModel
             Write-Warning "[Markdown generation] Could not find parameter object for $ParameterName in command $($Command.Name)"    
         }
     }
-
-    # handle CommonParameters and CommonWorkflowParameters
-    if ($Command.CommandType -eq 'Function' -and $Command.CmdletBinding -eq $false)
-    {
-        # this is a really weired case, it may never appear in real modules
-        $MamlCommandObject.SupportCommonParameters = $false
-    }
-    else 
+    
+    # Handle CommonParameters, default for MamlCommand is SupportCommonParameters = $true
+    if ($Command.CmdletBinding -eq $false)
     {
+        # Remove CommonParameters by exception
         $MamlCommandObject.SupportCommonParameters = $false
     }
 
+    # Handle CommonWorkflowParameters
     $MamlCommandObject.IsWorkflow = $IsWorkflow
 
     #endregion

test/Pester/PlatyPs.Tests.ps1

@@ -67,11 +67,30 @@ Describe 'New-MarkdownHelp' {
 
                 }
 
+                function Get-AdvancedFn
+                {
+                    [CmdletBinding()]
+                    param (
+
+                    )
+                }
+
+                function Get-SimpleFn
+                {
+                    param (
+                    
+                    )
+                }
+
                 function Set-BBBB 
                 {
 
                 }
 
+                Workflow FromCommandWorkflow {
+
+                }
+
                 # Set-Alias and New-Alias provide two different results
                 # when `Get-Command -module Foo` is used to list commands.
                 Set-Alias aaaaalias Get-AAAA
@@ -82,7 +101,7 @@ Describe 'New-MarkdownHelp' {
                 Export-ModuleMember -Alias Fork-AAAA
                 Export-ModuleMember -Alias aaaaalias
                 Export-ModuleMember -Alias bbbbalias
-                Export-ModuleMember -Function Get-AAAA
+                Export-ModuleMember -Function 'Get-AAAA','Get-AdvancedFn','Get-SimpleFn','FromCommandWorkflow'
 
             } | Import-Module -Force
 
@@ -94,9 +113,21 @@ Describe 'New-MarkdownHelp' {
         }
 
         It 'generates markdown files only for exported functions' {
-            ($files | Measure-Object).Count | Should Be 1
-            $files.Name | Should Be 'Get-AAAA.md'
-        }        
+            ($files | Measure-Object).Count | Should Be 4
+            $files.Name | Should -BeIn 'Get-AAAA.md','Get-AdvancedFn.md','Get-SimpleFn.md','FromCommandWorkflow.md'
+        }
+
+        It 'generates markdown that includes CommonParameters in advanced functions' {
+            ($files | Where-Object -FilterScript { $_.Name -eq 'Get-AdvancedFn.md' }).FullName | Should -FileContentMatch '### CommonParameters'
+        }
+
+        It 'generates markdown that excludes CommonParameters from simple functions' {
+            ($files | Where-Object -FilterScript { $_.Name -eq 'Get-SimpleFn.md' }).FullName | Should -FileContentMatch -Not '### CommonParameters'
+        }
+
+        It 'generates markdown for workflows with CommonParameters' {
+            ($files | Where-Object -FilterScript { $_.Name -eq 'FromCommandWorkflow.md' }).FullName | Should -FileContentMatch '### CommonParameters'
+        }
     }
 
     Context 'from command' {
@@ -410,7 +441,7 @@ Type: System.Management.Automation.SwitchParameter
 
 '@ 
             $expectedSyntax = normalizeEnds @'
-Get-Alpha [-WhatIf] [[-CCC] <String>] [[-ddd] <Int32>]
+Get-Alpha [-WhatIf] [[-CCC] <String>] [[-ddd] <Int32>] [<CommonParameters>]
 
 '@
 
@@ -428,7 +459,7 @@ Type: SwitchParameter
 
 '@ 
             $expectedSyntax = normalizeEnds @'
-Get-Alpha [-WhatIf] [[-CCC] <String>] [[-ddd] <Int32>]
+Get-Alpha [-WhatIf] [[-CCC] <String>] [[-ddd] <Int32>] [<CommonParameters>]
 
 '@