Improve Inputs based on SYNOPSIS

[Gijsreyn]

Summary of the new feature / enhancement

As a user, I want to be able to set the Inputs based on the synopsis. Whenever I'm using:

.INPUTS
Test

The result doesn't display the description:

Alternatively, and this might be another issue, whenever a parameter has the ValueFromPipeline added, the Inputs contains this parameter somehow.

Proposed technical implementation details (optional)

No response

[sdwheeler]

@Gijsreyn I don't understand what you are asking for. Can you provide a reproducible example we can test with?

[Gijsreyn]

Grabbing the example from issue #765:

Function Get-Test {
    <#
    .SYNOPSIS
        Outputs a greeting message.

    .DESCRIPTION
        This function outputs a greeting message.

    .PARAMETER Name
        The name of the person to greet.

    .EXAMPLE
        Get-Test -Name "World"
    .NOTES
        Additional information about the function
    .INPUTS
        System.String

        Provide a valid name to the Name parameter
    .LINK
        - https://example.com/documentation
    #>
    [CmdletBinding()]
    param (
        [Parameter(Mandatory = $true)]
        [string]$Name
    )

    Write-Output "Hello, $Name! This is a test function."
}

Perhaps my expectations are wrong, but what I would expect now is that the typeName will be System.String and the description will be filled in, but it isn't the case:

Now, if I add the ValueFromPipeline attribute, I'm getting an additional one in the Inputs:

How would I be able to fill in the description directly here?

[sdwheeler]

OK, I see what is happening here. PlatyPS get the comment-based help from Get-Help, which parsers the .INPUT text as a single multi-line value.

PS> $h = Get-Help Get-Test -full
PS> $h.inputTypes | gm

   TypeName: MamlCommandHelpInfo#inputTypes

Name        MemberType   Definition
----        ----------   ----------
Equals      Method       bool Equals(System.Object obj)
GetHashCode Method       int GetHashCode()
GetType     Method       type GetType()
ToString    Method       string ToString()
inputType   NoteProperty MamlCommandHelpInfo#inputType inputType=@{type=@{name=System.String…

PS> $h.inputTypes.inputType.type | fl

name : System.String

       Provide a valid name to the Name parameter

This is really a problem with how the help system works. I don't know what we could change in PlatyPS to fix it.

[Bill-Stewart]

Is this the same issue as this SO question?

https://stackoverflow.com/questions/54888628/

If so, one workaround is to post-process the INPUTS and OUTPUTS sections in the markdown output as noted in the answer I posted there.

[Gijsreyn]

Hey @Bill-Stewart,

With Microsoft.PowerShell.PlatyPS, the model has changed slightly differently, and I think it is doable differently without using regex.

Firstly, before showing the technique, I would have expected an easy post-processing if I were looking at the INPUTS itself on the object:

I would have expected this to work. @sdwheeler, is this another bug?

Coming back to the post-processing, you can build up the model like this:

# Create the help object
$commandHelpObject = New-CommandHelp -CommandInfo (Get-Command Get-Test)

# Create your own InputOutput object
$inputOutput = [Microsoft.PowerShell.PlatyPS.Model.InputOutput]::new('System.String', 'Provide a valid description')
$list = [System.Collections.Generic.List[Microsoft.PowerShell.PlatyPS.Model.Parameter]]::new()
$list.Add($inputOutput)

# Get the property from the help object
$property = $commandHelpObject.GetType().GetProperty('Inputs')

# This is able to use SetValue()
$property.SetValue($commandHelpObject, $inputOutput, $null)

[sdwheeler]

This is a comment-based help problem. The .INPUTS and .OUTPUTS keywords are intended to have a single type name as the description. If you provide more than that, whatever text you include is put into the object property returned by Get-Help. That content doesn't work with PlatyPS.

[Bill-Stewart]

So yes, it is the same underlying issue as the SO question I posted: Get-Help output doesn't differentiate between the type name and description, so there's no way for platyPS to differentiate type name from description in its own output. One workaround (as noted in my SO answer) is to post-process the markdown so it matches the platyPS schema.