xmlpowershellmaml

.Xml help doesn't display parameter placeholders in SYNTAX section

I have a PowerShell function in a .ps1 file. The function has two parameter sets with one parameter each. The param() block in the function declaration is:

Function Restore-ExplorerWindow
{
    param(
        [Parameter(ParameterSetName = 'ByPath',
            Mandatory,
            Position=0,
            ValueFromPipeline)]
        [ValidateScript({Test-Path $_ -PathType 'Leaf'})]
        [String[]]
        $Path,
        [Parameter(ParameterSetName = 'ByObject',
            Mandatory,
            Position=0,
            ValueFromPipeline)]
        [System.Object[]]
        $ExplorerState
    )

Without any help defined, PowerShell generates the following:

SYNTAX
    Restore-ExplorerWindow [-Path] <string[]>  [<CommonParameters>]

    Restore-ExplorerWindow [-ExplorerState] <Object[]>  [<CommonParameters>]


PARAMETERS
    -ExplorerState <Object[]>

        Required?                    true
        Position?                    0
        Accept pipeline input?       true (ByValue)
        Parameter set name           ByObject
        Aliases                      None
        Dynamic?                     false

    -Path <string[]>

        Required?                    true
        Position?                    0
        Accept pipeline input?       true (ByValue)
        Parameter set name           ByPath
        Aliases                      None
        Dynamic?                     false

But when I specify a seemingly functional .xml help file, which has the following SYNTAX and PARAMETERS nodes:

    <command:syntax>
      <command:syntaxItem>
        <maml:name>Restore-ExplorerWindow</maml:name>
        <command:parameter
         required="true"
         variableLength="true"
         globbing="false"
         pipelineInput="true"
         position="0"
         aliases="none">
          <maml:name>Path</maml:name>
          <dev:type>
            <maml:name>System.String[]</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>none</dev:defaultValue>
        </command:parameter>
      </command:syntaxItem>
      <command:syntaxItem>
        <maml:name>Restore-ExplorerWindow</maml:name>
        <command:parameter
         required="true"
         variableLength="true"
         globbing="false"
         pipelineInput="true"
         position="0"
         aliases="none">
          <maml:name>ExplorerState</maml:name>
          <dev:type>
            <maml:name>System.Object[]</maml:name>
            <maml:uri />
          </dev:type>
          <dev:defaultValue>none</dev:defaultValue>
        </command:parameter>
      </command:syntaxItem>
     </command:syntax>
    <command:parameters>
      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true" position="0" aliases="none">
        <maml:name>Path</maml:name>
        <maml:description>
          <maml:para>Path to previously exported .xml file.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.String[]</command:parameterValue>
        <dev:type>
          <maml:name>System.String[]</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>none</dev:defaultValue>
      </command:parameter>
      <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="true" position="0" aliases="none">
        <maml:name>ExplorerState</maml:name>
        <maml:description>
          <maml:para>Custom object created by `Get-ExplorerWindow`.</maml:para>
        </maml:description>
        <command:parameterValue required="true" variableLength="true">System.Object[]</command:parameterValue>
        <dev:type>
          <maml:name>System.Object[]</maml:name>
          <maml:uri />
        </dev:type>
        <dev:defaultValue>none</dev:defaultValue>
      </command:parameter>
    </command:parameters>

Get-Help displays the following:

SYNTAX
    Restore-ExplorerWindow [-Path] [<CommonParameters>]

    Restore-ExplorerWindow [-ExplorerState] [<CommonParameters>]


DESCRIPTION
    Opens an Explorer window using the information saved by `Get-ExplorerWindow`.


PARAMETERS
    -Path <System.String[]>
        Path to previously exported .xml file.

        Required?                    true
        Position?                    0
        Default value                none
        Accept pipeline input?       true
        Accept wildcard characters?  false

    -ExplorerState <Object[]>
        Custom object created by `Get-ExplorerWindow`.

        Required?                    true
        Position?                    0
        Default value                none
        Accept pipeline input?       true
        Accept wildcard characters?  false

I can't figure out why I'm not seeing:

SYNTAX
    Restore-ExplorerWindow [-Path] <string[]>  [<CommonParameters>]

    Restore-ExplorerWindow [-ExplorerState] <Object[]>  [<CommonParameters>]

with the xml help.

Solution

  • Your <command:syntaxItem> elements are each missing a <command:parameterValue> child element.

    Simply duplicate the elements of that name already defined later as <command:parameter> child elements.

    The documentation of the XML-based MAML format PowerShell help files use is How to Create the Cmdlet Help File

    You can avoid the problem you encountered - notably the need to duplicate information across elements - by authoring your help files with the help of the PlatyPS module (install with Install-Module PlatyPS), which auto-generates the MAML XML from Markdown files that it scaffolds from a given module's implementation.

    Note: