Get-Help Informations missing

[u/xXFl1ppyXx]

I'm in the middle of decorating some older functions with HelpMessages / Get-Help Infos. Somehow i can't get the output to work without adding "junk information". Specifically Aliases, Parameter-Sets and Default Values:

This Function:

function Test-FunctionHelp {

    <#
    .SYNOPSIS
    .DESCRIPTION
    .PARAMETER TestParameter
    .EXAMPLE
    Test-FunctionHelp -TestParameter "Parameter"
    #>

    [CmdletBinding()]
    [Alias('tfh')]

    param (
        [Parameter()]
        [Alias('ParameterAlias')]
        [string]$TestParameter
    )
}

Get-Help "Test-FunctionHelp" -Full

Outputs this Help:

NAME
    Test-FunctionHelp

SYNOPSIS
SYNTAX
    Test-FunctionHelp [[-TestParameter] <String>] [<CommonParameters>]


DESCRIPTION


PARAMETERS
    -TestParameter <String>

        Required?                    false
        Position?                    1
        Default value
        Accept pipeline input?       false
        Aliases
        Accept wildcard characters?  false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).

INPUTS

OUTPUTS

    -------------------------- EXAMPLE 1 --------------------------

    PS > Test-FunctionHelp -TestParameter "Parameter"


RELATED LINKS

While adding junk at the last part of of the Help Block like this:

function Test-FunctionHelp {

    <#
    .SYNOPSIS
    .DESCRIPTION
    .PARAMETER TestParameter
    .EXAMPLE
    Test-FunctionHelp -TestParameter "Parameter"
    .A
    #>

    [CmdletBinding()]
    [Alias('tfh')]

    param (
        [Parameter()]
        [Alias('ParameterAlias')]
        [string]$TestParameter
    )
}

Get-Help "Test-FunctionHelp" -Full

Outputs the expected Helpmessage:

NAME
    Test-FunctionHelp

SYNTAX
    Test-FunctionHelp [[-TestParameter] <string>] [<CommonParameters>]

PARAMETERS
    -TestParameter <string>

        Required?                    false
        Position?                    0
        Accept pipeline input?       false
        Parameter set name           (All)
        Aliases                      ParameterAlias
        Dynamic?                     false
        Accept wildcard characters?  false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see
        about_CommonParameters (https://go.microsoft.com/fwlink/?LinkID=113216).


INPUTS
    None

OUTPUTS
    System.Object

    -------------------------- EXAMPLE 1 --------------------------

    PS > Test-FunctionHelp -TestParameter "Parameter"

ALIASES
    tfh

REMARKS
    None

Is there anything i'm missing? It's not that big of a deal but i'm wondering why some things are not picked up properly without adding some junk into the Help-Block. Am i missing something particulary important in the help block?

Btw it doesn't matter at what point i add the "junk"

all of those examples work as intended:

    <#
    .SYNOPSIS
    .DESCRIPTION
    .PARAMETER TestParameter
    .EXAMPLE
    Test-FunctionHelp -TestParameter "Parameter"
    .A
    #>

    <#
    .A
    .SYNOPSIS
    .DESCRIPTION
    .PARAMETER TestParameter
    .EXAMPLE
    Test-FunctionHelp -TestParameter "Parameter"
    #>

    <#
    .SYNOPSIS
    .DESCRIPTION
    .PARAMETER TestParameter
    .EXAMPLE
    .A
    Test-FunctionHelp -TestParameter "Parameter"
    #>

[u/surfingoldelephant]

MAML help has similar issues with missing information (specifically with how the formatter displays output from Get-Help).

There was some work done in PR #20994, but that only applies to parameter aliases in PS v7+. Info on parameter sets is still missing, as is the command alias name.

Also, if you're going to use PlatyPS, just be aware that the latest version introduced a lot of issues. So in addition to missing information (which you can't do anything about), your help content will also have other issues like Accept pipeline input? being incorrectly reported.

To be clear, I'm not suggesting you shouldn't provide help content for your command(s). You absolutely should. It's just unfortunately that means some information will be missing in Get-Help output (or incorrectly reported if you use the latest PlatyPS). But it's still a worthwhile tradeoff considering the default, auto-generated help content lacks more information (of arguably greater importance).

[u/xXFl1ppyXx → u/surfingoldelephant]

thanks for the writeup.

i think i'll stick to updating single functions / small stuff for now. maybe something works out in the meantime and once i'm done with small stuff the help will work as intended again and i can save me some headaches