support use fulltypename (#275)

Author: yishengjin1413

docs/New-MarkdownHelp.md

@@ -14,22 +14,23 @@ Creates help in markdown format.
 ### FromModule
 ```
 New-MarkdownHelp -Module <String[]> [-Force] [-AlphabeticParamsOrder] [-Metadata <Hashtable>]
- -OutputFolder <String> [-NoMetadata] [-Encoding <Encoding>] [-WithModulePage] [-Locale <String>]
- [-HelpVersion <String>] [-FwLink <String>] [<CommonParameters>]
+ -OutputFolder <String> [-NoMetadata] [-UseFullTypeName] [-Encoding <Encoding>] [-WithModulePage]
+ [-Locale <String>] [-HelpVersion <String>] [-FwLink <String>] [<CommonParameters>]
 ```
 
 ### FromCommand
 ```
 New-MarkdownHelp -Command <String[]> [-Force] [-AlphabeticParamsOrder] [-Metadata <Hashtable>]
- [-OnlineVersionUrl <String>] -OutputFolder <String> [-NoMetadata] [-Encoding <Encoding>] [<CommonParameters>]
+ [-OnlineVersionUrl <String>] -OutputFolder <String> [-NoMetadata] [-UseFullTypeName] [-Encoding <Encoding>]
+ [<CommonParameters>]
 ```
 
 ### FromMaml
 ```
 New-MarkdownHelp -MamlFile <String[]> [-ConvertNotesToList] [-ConvertDoubleDashLists] [-Force]
- [-AlphabeticParamsOrder] [-Metadata <Hashtable>] -OutputFolder <String> [-NoMetadata] [-Encoding <Encoding>]
- [-WithModulePage] [-Locale <String>] [-HelpVersion <String>] [-FwLink <String>] [-ModuleName <String>]
- [-ModuleGuid <String>] [<CommonParameters>]
+ [-AlphabeticParamsOrder] [-Metadata <Hashtable>] -OutputFolder <String> [-NoMetadata] [-UseFullTypeName]
+ [-Encoding <Encoding>] [-WithModulePage] [-Locale <String>] [-HelpVersion <String>] [-FwLink <String>]
+ [-ModuleName <String>] [-ModuleGuid <String>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -426,6 +427,21 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -UseFullTypeName
+Indicates that the target document will use a full type name instead of a short name for parameters.
+
+```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).
 

docs/Update-MarkdownHelp.md

@@ -13,7 +13,7 @@ Update PlatyPS markdown help files.
 
 ```
 Update-MarkdownHelp [-Path] <String[]> [[-Encoding] <Encoding>] [[-LogPath] <String>] [-LogAppend]
- [-AlphabeticParamsOrder] [<CommonParameters>]
+ [-AlphabeticParamsOrder] [-UseFullTypeName] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -157,6 +157,21 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -UseFullTypeName
+Indicates that the target document will use a full type name instead of a short name for parameters.
+
+```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).
 

src/platyPS/platyPS.psm1

@@ -74,6 +74,8 @@ function New-MarkdownHelp
         [string]$OutputFolder,
 
         [switch]$NoMetadata,
+        
+        [switch]$UseFullTypeName,
 
         [System.Text.Encoding]$Encoding = $script:UTF8_NO_BOM,
 
@@ -227,7 +229,7 @@ function New-MarkdownHelp
                     throw "Command $_ not found in the session."
                 }
 
-                GetMamlObject -Cmdlet $_ | processMamlObjectToFile
+                GetMamlObject -Cmdlet $_ -UseFullTypeName:$UseFullTypeName | processMamlObjectToFile
             }
         }
         else 
@@ -249,7 +251,7 @@ function New-MarkdownHelp
                         throw "Module $_ is not imported in the session. Run 'Import-Module $_'."
                     }
 
-                    GetMamlObject -Module $_ | processMamlObjectToFile
+                    GetMamlObject -Module $_ -UseFullTypeName:$UseFullTypeName | processMamlObjectToFile
 
                     $ModuleName = $_
                     $ModuleGuid = (Get-Module $ModuleName).Guid
@@ -342,7 +344,8 @@ function Update-MarkdownHelp
 
         [string]$LogPath,
         [switch]$LogAppend,
-        [switch]$AlphabeticParamsOrder
+        [switch]$AlphabeticParamsOrder,
+        [switch]$UseFullTypeName
     )
 
     begin
@@ -408,7 +411,7 @@ function Update-MarkdownHelp
             # update the help file entry in the metadata
             $metadata = Get-MarkdownMetadata $filePath
             $metadata["external help file"] = GetHelpFileName $command
-            $reflectionModel = GetMamlObject -Cmdlet $name
+            $reflectionModel = GetMamlObject -Cmdlet $name -UseFullTypeName:$UseFullTypeName
 
             $merger = New-Object Markdown.MAML.Transformer.MamlModelMerger -ArgumentList $infoCallback
             $newModel = $merger.Merge($reflectionModel, $oldModel)
@@ -1926,7 +1929,8 @@ function GetMamlObject
         [parameter(parametersetname="Maml")]
         [switch] $ConvertNotesToList,
         [parameter(parametersetname="Maml")]
-        [switch] $ConvertDoubleDashLists
+        [switch] $ConvertDoubleDashLists,
+        [switch] $UseFullTypeName
     )
 
     function CommandHasAutogeneratedSynopsis
@@ -1941,7 +1945,7 @@ function GetMamlObject
         Write-Verbose ("Processing: " + $Cmdlet)
         $Help = Get-Help $Cmdlet
         $Command = Get-Command $Cmdlet
-        return ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UsePlaceholderForSynopsis:(CommandHasAutogeneratedSynopsis $Help)
+        return ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UsePlaceholderForSynopsis:(CommandHasAutogeneratedSynopsis $Help) -UseFullTypeName:$UseFullTypeName
     }
     elseif ($Module)
     {
@@ -1953,7 +1957,7 @@ function GetMamlObject
             Write-Verbose ("`tProcessing: " + $Command.Name)
             $Help = Get-Help $Command.Name
             # yeild
-            ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UsePlaceholderForSynopsis:(CommandHasAutogeneratedSynopsis $Help)
+            ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UsePlaceholderForSynopsis:(CommandHasAutogeneratedSynopsis $Help)  -UseFullTypeName:$UseFullTypeName
         }
     }
     else # Maml
@@ -1974,7 +1978,7 @@ function GetMamlObject
             }
 
             # yeild
-            ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UseHelpForParametersMetadata
+            ConvertPsObjectsToMamlModel -Command $Command -Help $Help -UseHelpForParametersMetadata  -UseFullTypeName:$UseFullTypeName
         }
     }
 }
@@ -2036,7 +2040,8 @@ function ConvertPsObjectsToMamlModel
         [Parameter(Mandatory=$true)]
         [object]$Help,
         [switch]$UseHelpForParametersMetadata,
-        [switch]$UsePlaceholderForSynopsis
+        [switch]$UsePlaceholderForSynopsis,
+        [switch]$UseFullTypeName
     )
 
     function isCommonParameterName
@@ -2239,12 +2244,18 @@ function ConvertPsObjectsToMamlModel
                 }
 
                 $ParameterObject = New-Object -TypeName Markdown.MAML.Model.MAML.MamlParameter
-                $ParameterType = $Parameter.ParameterType
-                $ParameterObject.Type = getTypeString -typeObject $ParameterType
                 $ParameterObject.Name = $Parameter.Name
                 $ParameterObject.Required = $Parameter.IsMandatory
                 $ParameterObject.PipelineInput = getPipelineValue $Parameter
-
+                $ParameterType = $Parameter.ParameterType
+                $ParameterObject.Type = if ($UseFullTypeName)
+                {
+                    $ParameterType.FullName
+                }
+                else
+                {
+                    getTypeString -typeObject $ParameterType
+                }
                 $ParameterObject.ValueRequired = -not ($Parameter.Type -eq "SwitchParameter") # thisDefinition is a heuristic
 
                 foreach($Alias in $Parameter.Aliases)

test/Pester/PlatyPs.Tests.ps1

@@ -7,6 +7,10 @@ $outFolder = "$root\out"
 Import-Module $outFolder\platyPS -Force
 
 Describe 'New-MarkdownHelp' {
+    function normalizeEnds([string]$text)
+    {
+        $text -replace "`r`n?|`n", "`r`n"
+    }
 
     Context 'errors' {
         It 'throw when cannot find module' {
@@ -122,16 +126,18 @@ Describe 'New-MarkdownHelp' {
         }
 
         It 'uses alphabetic order when specified' {
-            $files = New-MarkdownHelp -Command Get-Alpha -OutputFolder TestDrive:\alpha -Force -AlphabeticParamsOrder
-            ($files | Measure-Object).Count | Should Be 1
-            Get-Content $files | Where-Object {$_.StartsWith('### -')} | Out-String | Should Be @'
+            
+            $expectedOrder = normalizeEnds @'
 ### -AAA
 ### -BBB
 ### -CCC
 ### -Confirm
 ### -WhatIf
 
 '@
+            $files = New-MarkdownHelp -Command Get-Alpha -OutputFolder TestDrive:\alpha -Force -AlphabeticParamsOrder
+            ($files | Measure-Object).Count | Should Be 1
+            Get-Content $files | Where-Object {$_.StartsWith('### -')} | Out-String | Should Be $expectedOrder
         }
     }
 
@@ -379,6 +385,54 @@ Describe 'New-MarkdownHelp' {
 
         }
     }
+	
+	Context 'Full Type Name' {
+        function global:Get-Alpha
+        {
+            param(
+                [Switch]
+                [Parameter(Position=1)]
+                $WhatIf,
+                [string]
+                [Parameter(Position=2)]
+                $CCC
+            )
+        }
+
+        It 'use full type name when specified' {
+            $expectedParameters = normalizeEnds @'
+Type: System.String
+Type: System.Management.Automation.SwitchParameter
+
+'@ 
+            $expectedSyntax = normalizeEnds @'
+Get-Alpha [[-WhatIf] <System.Management.Automation.SwitchParameter>] [[-CCC] <System.String>]
+
+'@
+
+            $files = New-MarkdownHelp -Command Get-Alpha -OutputFolder TestDrive:\alpha -Force -AlphabeticParamsOrder -UseFullTypeName
+            ($files | Measure-Object).Count | Should Be 1
+            Get-Content $files | Where-Object {$_.StartsWith('Type: ')} | Out-String | Should Be $expectedParameters
+            Get-Content $files | Where-Object {$_.StartsWith('Get-Alpha')} | Out-String | Should Be $expectedSyntax
+        }
+
+        It 'not use full type name when specified' {
+            $expectedParameters = normalizeEnds @'
+Type: String
+Type: SwitchParameter
+
+'@ 
+            $expectedSyntax = normalizeEnds @'
+Get-Alpha [-WhatIf] [[-CCC] <String>]
+
+'@
+
+            $files = New-MarkdownHelp -Command Get-Alpha -OutputFolder TestDrive:\alpha -Force -AlphabeticParamsOrder
+            ($files | Measure-Object).Count | Should Be 1
+            Get-Content $files | Where-Object {$_.StartsWith('Type: ')} | Out-String | Should Be $expectedParameters
+            Get-Content $files | Where-Object {$_.StartsWith('Get-Alpha')} | Out-String | Should Be $expectedSyntax
+        }
+    }
 }
 
 
@@ -807,6 +861,44 @@ It has mutlilines. And hyper (http://link.com).
         Update-MarkdownHelp -Path $outputFolder
         (Get-Content (Join-Path $outputOriginal Add-Computer.md)) | Should Be (Get-Content (Join-Path $outputUpdated Add-Computer.md))
     }
+
+    It 'parameter type should not be fullname' {
+        $expectedParameters = normalizeEnds @'
+Type: String
+Type: String
+
+'@ 
+        $expectedSyntax = normalizeEnds @'
+Get-MyCoolStuff [[-Foo] <String>] [[-Bar] <String>] [<CommonParameters>]
+
+'@
+        $v2md | Get-Content | Where-Object {$_.StartsWith('Type: ')} | Out-String | Should Be $expectedParameters
+        $v2md | Get-Content | Where-Object {$_.StartsWith('Get-MyCoolStuff')} | Out-String | Should Be $expectedSyntax
+    }
+
+    $v3md = Update-MarkdownHelp $v2md -Verbose -AlphabeticParamsOrder -UseFullTypeName
+
+    $v3markdown = $v3md | Get-Content
+
+    It 'parameter type should be fullname' {
+        $expectedParameters = normalizeEnds @'
+Type: System.String
+Type: System.String
+
+'@ 
+        $expectedSyntax = normalizeEnds @'
+Get-MyCoolStuff [[-Foo] <System.String>] [[-Bar] <System.String>] [<CommonParameters>]
+
+'@
+        $v3markdown | Where-Object {$_.StartsWith('Type: ')} | Out-String | Should Be $expectedParameters
+        $v3markdown | Where-Object {$_.StartsWith('Get-MyCoolStuff')} | Out-String | Should Be $expectedSyntax
+    }
+
+    It 'all the other part should be the same except line with parameters' {
+        $expectedContent = $v2md | Get-Content | Select-String -pattern "Type: |Get-MyCoolStuff" -notmatch | Out-String
+        $v3markdown | Select-String -pattern "Type: |Get-MyCoolStuff" -notmatch | Out-String | Should Be $expectedContent
+    
+    }
 }
 
 Describe 'Update Markdown Help' {