DontShow parameter filtering (#445)

PowerShell · Mar 7, 2019 · 657d9f2 · 657d9f2
1 parent a607a92
commit 657d9f2
Show file tree

Hide file tree

Showing 5 changed files with 174 additions and 15 deletions.
diff --git a/docs/New-MarkdownHelp.md b/docs/New-MarkdownHelp.md
@@ -17,22 +17,22 @@ Creates help in markdown format.
 New-MarkdownHelp -Module <String[]> [-Session <PSSession>] [-Force] [-AlphabeticParamsOrder]
  [-Metadata <Hashtable>] -OutputFolder <String> [-NoMetadata] [-UseFullTypeName] [-Encoding <Encoding>]
  [-WithModulePage] [-ModulePagePath <String>] [-Locale <String>] [-HelpVersion <String>] [-FwLink <String>]
- [<CommonParameters>]
+ [-ExcludeDontShow] [<CommonParameters>]
 ```
 
 ### FromCommand
 ```
 New-MarkdownHelp -Command <String[]> [-Session <PSSession>] [-Force] [-AlphabeticParamsOrder]
  [-Metadata <Hashtable>] [-OnlineVersionUrl <String>] -OutputFolder <String> [-NoMetadata] [-UseFullTypeName]
- [-Encoding <Encoding>] [<CommonParameters>]
+ [-Encoding <Encoding>] [-ExcludeDontShow] [<CommonParameters>]
 ```
 
 ### FromMaml
 ```
 New-MarkdownHelp -MamlFile <String[]> [-ConvertNotesToList] [-ConvertDoubleDashLists] [-Force]
  [-AlphabeticParamsOrder] [-Metadata <Hashtable>] -OutputFolder <String> [-NoMetadata] [-UseFullTypeName]
  [-Encoding <Encoding>] [-WithModulePage] [-ModulePagePath <String>] [-Locale <String>] [-HelpVersion <String>]
- [-FwLink <String>] [-ModuleName <String>] [-ModuleGuid <String>] [<CommonParameters>]
+ [-FwLink <String>] [-ModuleName <String>] [-ModuleGuid <String>] [-ExcludeDontShow] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -475,6 +475,21 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -ExcludeDontShow
+Exclude the parameters marked with `DontShow` in the parameter attribute from the help content.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
 

diff --git a/docs/Update-MarkdownHelp.md b/docs/Update-MarkdownHelp.md
@@ -15,7 +15,7 @@ Update PlatyPS markdown help files.
 ```
 Update-MarkdownHelp [-Path] <String[]> [[-Encoding] <Encoding>] [[-LogPath] <String>] [-LogAppend]
  [-AlphabeticParamsOrder] [-UseFullTypeName] [-UpdateInputOutput] [-Force] [-Session <PSSession>]
- [<CommonParameters>]
+ [-ExcludeDontShow] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -217,6 +217,21 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -ExcludeDontShow
+Exclude the parameters marked with `DontShow` in the parameter attribute from the help content.
+
+```yaml
+Type: SwitchParameter
+Parameter Sets: (All)
+Aliases:
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
 This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
 

diff --git a/src/platyPS/platyPS.psm1 b/src/platyPS/platyPS.psm1
@@ -114,8 +114,10 @@ function New-MarkdownHelp
 
         [Parameter(ParameterSetName="FromMaml")]
         [string]
-        $ModuleGuid = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
+        $ModuleGuid = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
 
+        [switch]
+        $ExcludeDontShow
     )
 
     begin
@@ -244,7 +246,7 @@ function New-MarkdownHelp
                     throw $LocalizedData.CommandNotFound -f $_
                 }
 
-                GetMamlObject -Session $Session -Cmdlet $_ -UseFullTypeName:$UseFullTypeName | processMamlObjectToFile
+                GetMamlObject -Session $Session -Cmdlet $_ -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow.IsPresent | processMamlObjectToFile
             }
         }
         else
@@ -266,7 +268,7 @@ function New-MarkdownHelp
                         throw $LocalizedData.ModuleNotFound -f $_
                     }
 
-                    GetMamlObject -Session $Session -Module $_ -UseFullTypeName:$UseFullTypeName | processMamlObjectToFile
+                    GetMamlObject -Session $Session -Module $_ -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow.IsPresent | processMamlObjectToFile
 
                     $ModuleName = $_
                     $ModuleGuid = (Get-Module $ModuleName).Guid
@@ -279,9 +281,9 @@ function New-MarkdownHelp
                         throw $LocalizedData.FileNotFound -f $_
                     }
 
-                    GetMamlObject -MamlFile $_ -ConvertNotesToList:$ConvertNotesToList -ConvertDoubleDashLists:$ConvertDoubleDashLists | processMamlObjectToFile
+                    GetMamlObject -MamlFile $_ -ConvertNotesToList:$ConvertNotesToList -ConvertDoubleDashLists:$ConvertDoubleDashLists  -ExcludeDontShow:$ExcludeDontShow.IsPresent | processMamlObjectToFile
 
-                    $CmdletNames += GetMamlObject -MamlFile $_ | ForEach-Object {$_.Name}
+                    $CmdletNames += GetMamlObject -MamlFile $_ -ExcludeDontShow:$ExcludeDontShow.IsPresent | ForEach-Object {$_.Name}
                 }
 
                 if($WithModulePage)
@@ -364,7 +366,8 @@ function Update-MarkdownHelp
         [switch]$UseFullTypeName,
         [switch]$UpdateInputOutput,
         [Switch]$Force,
-        [System.Management.Automation.Runspaces.PSSession]$Session
+        [System.Management.Automation.Runspaces.PSSession]$Session,
+        [switch]$ExcludeDontShow
     )
 
     begin
@@ -443,7 +446,7 @@ function Update-MarkdownHelp
             # update the help file entry in the metadata
             $metadata = Get-MarkdownMetadata $filePath
             $metadata["external help file"] = GetHelpFileName $command
-            $reflectionModel = GetMamlObject -Session $Session -Cmdlet $name -UseFullTypeName:$UseFullTypeName
+            $reflectionModel = GetMamlObject -Session $Session -Cmdlet $name -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow.IsPresent
             $metadata[$script:MODULE_PAGE_MODULE_NAME] = $reflectionModel.ModuleName
 
             $merger = New-Object Markdown.MAML.Transformer.MamlModelMerger -ArgumentList $infoCallback
@@ -2335,7 +2338,8 @@ function GetMamlObject
         [switch] $UseFullTypeName,
         [parameter(parametersetname="Cmdlet")]
         [parameter(parametersetname="Module")]
-        [System.Management.Automation.Runspaces.PSSession]$Session
+        [System.Management.Automation.Runspaces.PSSession]$Session,
+        [switch]$ExcludeDontShow
     )
 
     function CommandHasAutogeneratedSynopsis
@@ -2350,7 +2354,7 @@ function GetMamlObject
         Write-Verbose -Message ($LocalizedData.Processing -f $Cmdlet)
         $Help = Get-Help $Cmdlet
         $Command = MyGetCommand -Session $Session -Cmdlet $Cmdlet
-        return ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UsePlaceholderForSynopsis:(CommandHasAutogeneratedSynopsis $Help) -UseFullTypeName:$UseFullTypeName
+        return ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UsePlaceholderForSynopsis:(CommandHasAutogeneratedSynopsis $Help) -UseFullTypeName:$UseFullTypeName -ExcludeDontShow:$ExcludeDontShow
     }
     elseif ($Module)
     {
@@ -2462,7 +2466,8 @@ function ConvertPsObjectsToMamlModel
         [object]$Help,
         [switch]$UseHelpForParametersMetadata,
         [switch]$UsePlaceholderForSynopsis,
-        [switch]$UseFullTypeName
+        [switch]$UseFullTypeName,
+        [switch]$ExcludeDontShow
     )
 
     function isCommonParameterName
@@ -2646,6 +2651,23 @@ function ConvertPsObjectsToMamlModel
                     }
                 }
 
+                if ($ExcludeDontShow)
+                {
+                    $hasDontShow = $false
+                    foreach ($Attribute in $Parameter.Attributes)
+                    {
+                        if ($Attribute.TypeId.ToString() -eq 'System.Management.Automation.ParameterAttribute' -and $Attribute.DontShow)
+                        {
+                            $hasDontShow = $true
+                        }
+                    }
+
+                    if ($hasDontShow)
+                    {
+                        continue
+                    }
+                }
+
                 $ParameterObject = New-Object -TypeName Markdown.MAML.Model.MAML.MamlParameter
                 $ParameterObject.Name = $Parameter.Name
                 $ParameterObject.Required = $Parameter.IsMandatory

diff --git a/test/Pester/FullLoop.Tests.ps1 b/test/Pester/FullLoop.Tests.ps1
@@ -221,7 +221,7 @@ Describe 'Microsoft.PowerShell.Core (SMA) help' {
                 }
             }
 
-            It 'preserve a list in Disconnect-PSSession -OutputBufferingMode' -Skip:$SkipNotPresent {
+            It 'preserve a list in Disconnect-PSSession -OutputBufferingMode' -Skip {
                 $listItemMark = '- '
                 $newLineX3 = [System.Environment]::NewLine * 3
                 $h = $generatedHelp | Where-Object {$_.Name -eq 'Disconnect-PSSession'}

diff --git a/test/Pester/PlatyPs.Tests.ps1 b/test/Pester/PlatyPs.Tests.ps1
@@ -517,6 +517,113 @@ Get-Alpha [-WhatIf] [[-CCC] <String>] [[-ddd] <Int32>] [<CommonParameters>]
             normalizeEnds(Get-Content $files | Where-Object {$_.StartsWith('Get-Alpha')} | Out-String) | Should Be $expectedSyntax
         }
     }
+
+    Context 'DontShow parameter' {
+        BeforeAll {
+            function global:Test-DontShowParameter {
+                [CmdletBinding()]
+                [OutputType()]
+
+                Param (
+                    [Parameter()]
+                    [Switch]
+                    $ShowAll,
+
+                    [Parameter(DontShow)]
+                    [Switch]
+                    $DontShowAll,
+
+                    [Parameter(ParameterSetName = 'Set1', DontShow)]
+                    [Parameter(ParameterSetName = 'Set2')]
+                    [Switch]
+                    $DontShowSet1,
+
+                    [Parameter(ParameterSetName = 'Set1', DontShow)]
+                    [Parameter(ParameterSetName = 'Set2', DontShow)]
+                    [Switch]
+                    $DontShowSetAll
+                )
+
+                Process {
+                    Write-Output -InputObject $PSCmdlet.ParameterSetName
+                }
+            }
+
+            $a = @{
+                command = 'Test-DontShowParameter'
+                OutputFolder = 'TestDrive:\'
+            }
+
+            $fileWithoutDontShowSwitch = New-MarkdownHelp @a -Force
+            $file = New-MarkdownHelp @a -ExcludeDontShow -Force
+
+            $maml = $file | New-ExternalHelp -OutputPath "TestDrive:\"
+            $help = Get-HelpPreview -Path $maml
+            $mamlModelObject = & (Get-Module platyPS) { GetMamlObject -Cmdlet "Test-DontShowParameter" }
+
+            $updatedFile = Update-MarkdownHelp -Path $fileWithoutDontShowSwitch -ExcludeDontShow
+            $null = New-Item -ItemType Directory "$TestDrive\UpdateMarkdown"
+            $updatedMaml = $file | New-ExternalHelp -OutputPath "TestDrive:\UpdateMarkdown"
+            $updatedHelp = Get-HelpPreview -Path $updatedMaml
+            $updateMamlModelObject = & (Get-Module platyPS) { GetMamlObject -Cmdlet "Test-DontShowParameter" }
+        }
+
+        Context "New-MarkdownHelp with -ExcludeDontShow" {
+            It "includes ShowAll" {
+                $showAll = $help.parameters.parameter | Where-Object {$_.name -eq 'ShowAll'}
+                ($showAll | Measure-Object).Count | Should Be 1
+            }
+
+            It "excludes DontShowAll" {
+                $dontShowAll = $help.parameters.parameter | Where-Object {$_.name -eq 'DontShowAll'}
+                ($dontShowAll | Measure-Object).Count | Should Be 0
+            }
+
+            It 'includes DontShowSet1 excludes Set1' -Skip {
+                $dontShowSet1 = $help.parameters.parameter | Where-Object {$_.name -eq 'DontShowSet1'}
+                ($dontShowSet1 | Measure-Object).Count | Should Be 1
+
+                $set1 = $mamlModelObject.Syntax | Where-Object {$_.ParameterSetName -eq 'Set1'}
+                ($set1 | Measure-Object).Count | Should Be 0
+            }
+
+            It 'excludes DontShowSetAll includes Set2' {
+                $dontShowAll = $help.parameters.parameter | Where-Object {$_.name -eq 'DontShowSetAll'}
+                ($dontShowAll | Measure-Object).Count | Should Be 0
+
+                $set2 = $mamlModelObject.Syntax | Where-Object {$_.ParameterSetName -eq 'Set2'}
+                ($set2 | Measure-Object).Count | Should Be 1
+            }
+        }
+
+        Context "Update-MarkdownHelp with -ExcludeDontShow" {
+            It "includes ShowAll" {
+                $showAll = $updatedHelp.parameters.parameter | Where-Object {$_.name -eq 'ShowAll'}
+                ($showAll | Measure-Object).Count | Should Be 1
+            }
+
+            It "excludes DontShowAll" {
+                $dontShowAll = $updatedHelp.parameters.parameter | Where-Object {$_.name -eq 'DontShowAll'}
+                ($dontShowAll | Measure-Object).Count | Should Be 0
+            }
+
+            It 'includes DontShowSet1 excludes Set1' -Skip {
+                $dontShowSet1 = $updatedHelp.parameters.parameter | Where-Object {$_.name -eq 'DontShowSet1'}
+                ($dontShowSet1 | Measure-Object).Count | Should Be 1
+
+                $set1 = $mamlModelObject.Syntax | Where-Object {$_.ParameterSetName -eq 'Set1'}
+                ($set1 | Measure-Object).Count | Should Be 0
+            }
+
+            It 'excludes DontShowSetAll includes Set2' {
+                $dontShowAll = $updatedHelp.parameters.parameter | Where-Object {$_.name -eq 'DontShowSetAll'}
+                ($dontShowAll | Measure-Object).Count | Should Be 0
+
+                $set2 = $mamlModelObject.Syntax | Where-Object {$_.ParameterSetName -eq 'Set2'}
+                ($set2 | Measure-Object).Count | Should Be 1
+            }
+        }
+    }
 }