Powershell: Functionality, Component, and Role Comment-Based Help sections don't work as expected

Created on 19 Jun 2018 · 3Comments · Source: PowerShell/PowerShell

Steps to reproduce

PS C:\> Get-Help -Name Connect-Armor -Functionality
Get-Help : Missing an argument for parameter 'Functionality'. Specify a parameter of type 'System.String[]' and try again.
At line:1 char:30
+ Get-Help -Name Connect-Armor -Functionality
+                              ~~~~~~~~~~~~~~
+ CategoryInfo          : InvalidArgument: (:) [Get-Help], ParameterBindingException
+ FullyQualifiedErrorId : MissingArgument,Microsoft.PowerShell.Commands.GetHelpCommand

PS C:\> ( Get-Help -Name Connect-Armor ).Functionality
Armor session management

PS C:\> $help = Get-Help -Name Connect-Armor -Full; $help.Functionality
Armor session management

PS C:\> ( ( Get-Help -Name Connect-Armor -Full ).ToString() | Select-String -Pattern 'FUNCTIONALITY|COMPONENT' ).Count
0

PS C:\> Get-Help -Name Connect-Armor -Full | Select-String -Pattern 'FUNCTIONALITY|COMPONENT'

@{parameters=@{parameter=System.Management.Automation.PSObject[]}; inputTypes=@{inputType=@{type=@{name=None- this function does not accept pipeline inputs.}}}; returnValues=@{returnValue=@{type=@{name=ArmorSession}}};
alertSet=@{alert=System.Management.Automation.PSObject[]}; description=System.Management.Automation.PSObject[]; details=@{name=Connect-Armor}; examples=@{example=System.Management.Automation.PSObject[]};
relatedLinks=@{navigationLink=System.Management.Automation.PSObject[]}; syntax=@{syntaxItem=@{parameter=System.Management.Automation.PSObject[]; name=Connect-Armor}}; xmlns:maml=http://schemas.microsoft.com/maml/2004/10;
xmlns:command=http://schemas.microsoft.com/maml/dev/command/2004/10; xmlns:dev=http://schemas.microsoft.com/maml/dev/2004/10; Name=Connect-Armor; Category=Function; Synopsis=; Component=Armor API; Role=; Functionality=Armor session management; ModuleName=Armor}

Expected behavior

The new(ish) Functionality, Component, and Role help sections should output the section content for all standard use cases or a null string if not set.

Actual behavior

The Get-Help command throws an error if the corresponding parameter is called, and does not show up in the Full help output.

Environment data

6.0.2 + 6.1.0 preview 3

Reference: https://github.com/PowerShell/platyPS/issues/373

Issue-Question Resolution-Answered WG-Interactive-HelpSystem

Source

tlindsay42

All 3 comments

Here's what I think needs addressing (all points should probably be separate issues):

about_comment_based_help not providing guidance on how to fill in the .FUNCTIONALITY and .COMPONENT and .ROLE sections; it seems that no built-in cmdlets have these sections filled in.
Get-Help -Full / -Detailed not outputting these sections at all - they can only be retrieved as properties on the objects output by Get-Help
- A quick workaround is to pipe the Get-Help command to Format-List.

The unexpected stringification behavior of Get-Help output (see below).

As for Get-Help -Functionality / Get-Help -Component:

These are not _switches_ that output the section of interest.
Rather, they act as _filter parameters_ that accept one or more values (with wildcard support) to _select_ (list) help topics with matching sections.

In your case:

# Ditto for Get-Help -Component *armor*
PS> Get-Help  -Functionality *armor* 

Name                              Category  Module                    Synopsis                                                                                                                 
----                              --------  ------                    --------                                                                                                                 
Connect-Armor                     Function                            Connects to the Armor API and establishes a session.

As for your attempts to find information in the help text using Select-String:

The real test would be (and indeed it yields no result, because said sections are missing):

PS> Get-Help Connect-Armor -Full | Out-String -Stream | Select-String 'FUNCTIONALITY|COMPONENT'

That is, Out-String -Stream is needed for Select-String to operate on the same output as what would print to the console; it forces use of the default output formatting.

However - although it is a separate issue - the current behavior of implicit and explicit stringification is questionable:

Applying .ToString() directly always yields the empty string:

PS> '' -eq (Get-Help Get-ChildItem).ToString()
True

By contrast, _implicit_ stringification - which happens inside "..." and when piping to a string-binding cmdlet such as Select-Object - produces the equivalent of .psobject.ToString();

PS> (Get-Help Get-ChildItem).psobject.ToString()
@{alertSet=@{alert=System.Management.Automation.PSObject[]}; inputTypes=@{inputType=@{type=@{name=System.String}; description=System.Management.Automation.PSObject[]}}; relatedLinks=@{navigationLink=System.Management.Automation.PSObject[]}; details=@{verb=Get; noun=ChildItem; description=System.Management.Automation.PSObject[]; name=Get-ChildItem}; parameters=@{parameter=System.Management.Automation.PSObject[]}; examples=@{example=System.Management.Automation.PSObject[]}; returnValues=@{returnValue=System.Management.Automation.PSObject[]}; syntax=@{syntaxItem=System.Management.Automation.PSObject[]}; description=System.Management.Automation.PSObject[]; xmlns:maml=http://schemas.microsoft.com/maml/2004/10; xmlns:command=http://schemas.microsoft.com/maml/dev/command/2004/10; xmlns:dev=http://schemas.microsoft.com/maml/dev/2004/10; xmlns:MSHelp=http://msdn.microsoft.com/mshelp; Name=Get-ChildItem; Category=Cmdlet; Synopsis=Gets the items and child items in one or more specified locations.; Component=; Role=; Functionality=; PSSnapIn=; ModuleName=Microsoft.PowerShell.Management}

In fact, this behavior is tied to _type_ [pscustomobject], which is what Get-Help outputs: #6163 asks for .ToString() and .psobject.ToString() to be the same, though in the specific case of Get-Help output you could argue that the ETS should be used to provide a .ToString() method that renders the help _text_ (an implicit Out-String).