Search code examples
powershelldocumentation

Can I add a title to an example using comment-based documentation?

For example, Get-ChildItem has this in its help:

-- Example 9: Output for experimental feature PSUnixFileStat --

    PS> Get-ChildItem /etc/r*

When I run Get-Help on my stuff, the bar just says Example <number>.

Writing the following:

<#
.EXAMPLE Example title
example
#>

breaks Get-Help.

Do I need to use XML help or is there something else?

PS: The question submit form required me to not use "help" in the title. That's a bit silly in this case.

Solution

  • Do I need to use XML help or is there something else?

    Yes, you do need to use XML-based help in MAML format if you want to customize your example-command section titles. Authoring such help files is easiest via the PlatyPS module, which enables writing your help in Markdown format (*.md) files that are compiled to MAML format.

    You cannot customize example-command section titles via comment-based help (at least not as of PowerShell 7.2.x, but I suspect that won't change) - see the .EXAMPLE section documentation in the about_Comment_Based_Help conceptual help topic.

    • The topic shows that only a select few sections accept arguments, and - as you've observed - trying to use an argument where none are supported breaks the comment-based help altogether.