More detailed help for authoring (rather than just using) comment-based help

[jaberenberg]

Prerequisites

• Existing Issue: Search the existing issues for this repository. If there is an issue that fits your needs do not file a new one. Subscribe, react, or comment on that issue instead.
• Descriptive Title: Write the title for this issue as a short synopsis. If possible, provide context. For example, "Typo in Get-Foo cmdlet" instead of "Typo."
• Verify Version: If there is a mismatch between documentation and the behavior on your system, ensure that the version you are using is the same as the documentation. Check this box if they match or the issue you are reporting is not version specific.

Links

about_Comment_Based_Help

Summary

This was originally submitted at PowerShell Issue # 26071, where @mklement0 directed me to resubmit it here, PowerShell Docs. I was also referred to help topic about_comment_based_help, which I had already seen and incorporated into my issue comments.

Details

I am composing Get-Help compatible help text for my scripts and modules.
I am not using MAML or XML, simply comment-based text embedded in my
.ps1 and .psm1 files, and plain-text about_.help.txt files.

There is help for this authoring activity Out There, some of it contradictory
(section headings with or without a leading period), some of it lacking useful
detail (-Full provides more info than -Detailed -- but precisely what?),
and some of it seemingly incorrect: I can not, in general, use other than
the 7-bit character subset, even though my files are saved as UTF-8.
If I try an 8-bit character, Get-Help displays a don't-know character.

For my own private reference, I have compiled a brief guide. But if you find that
I've simply overlooked a site that covers what I've written, please set me straight.
Also if I'm wrong.

The read-only link to my MS OneDrive PowerShell folder. which contains my pdf, is PowerShell .

Suggested Fix

No response

[sdwheeler]

There is more information about Comment-based help in the SDK docs: https://learn.microsoft.com/powershell/scripting/developer/help/writing-comment-based-help-topics

But that doesn't answer all of your questions. Here are some answers:

• COMPONENT, ROLE, and FUNCTIONALITY - The help system in PowerShell was added in PowerShell v2.0 and hasn't changed much. These keywords were designed for Windows dev teams to describe the modules (or snap-ins) that they wrote. In practice, no one ever used these values. The object model created by Get-Help includes this information, so you have access to the information (if actually populated). But the values are only displayed in the list format generated when your help search returns multiple help topics.
• About topics - There are requirements for the layout of the first 5 lines of the text file so that Get-Help can parse the correct metadata. This is not officially documented. See this template for more information: https://github.com/juneb/PowerShellHelpDeepDive/blob/main/about_Topic_Template.help.txt. The template was created by June Blender. She used to write the documentation for PowerShell (many years ago). Her GitHub repo has a lot of useful information about help.
• Get-Help doesn't render markdown and never has. We would like to change that in future versions of PowerShell. But that is a long-term project without any resources at this time. Any markup included in your help text is treated as plain text.
• Auto-generated help content - See https://learn.microsoft.com/powershell/scripting/developer/help/autogenerated-elements-of-comment-based-help
• Character sets - UTF-8 encoded characters are supported. Save as UTF8 with BOM for best results.
• Line length - As you noticed long lines are wrapped without indentation resulting in ugly output in the console. We have a style guide for how we write the documentation: https://learn.microsoft.com/powershell/scripting/community/contributing/powershell-style-guide. We limit line length to 100-characters for cmdlet reference and 80-characters for About topics.

[jaberenberg]

@sdwheeler Thank you for your notes.

• COMPONENT, ROLE, and FUNCTIONALITY. I take it from your note that these are now deprecated, but kept around for downward compatibility.

• About topics. Your comment, that their first five lines of text can actually cause these files to be parsed for content, is surely of interest to authors and should be officially documented. The template to which you referred shows these lines as

1 TOPIC
2 about-topic
3
4 SHORT DESCRIPTION
5 description

The template specifies specific column numbers, and I wonder if this is a requirement for the parser or simply a suggestion.

• You write “Get-Help doesn't render markdown and never has.” OK, fine, but then all the official PowerShell help topics that display raw markdown should get updated. It’s cconfusing to read.

• Auto-generated help content. Thank you for the link, it confirms what I deduced and then documented in my pdf.’

• Character sets. OK I tried UTF8 with BOM and it works. Needs to be mentioned in an author’s guide.

• PowerShell-Docs style guide. Interesting and helpful collection of conventions. But in case you hadn’t noticed, it downright requires markdown for type names, class names, property names, etc.

And then we have some items from my pdf that you have not referred to.:

• Example first line ‘PS > ‘. That is, whatever I put in the first line after an .EXAMPLE header gets the ‘PS > ‘ slapped in front. Bug, or feature?

• Notes indentation.
Why is it so deep?
Got me to wondering if there’s some undocumented feature of Notes involving heading levels.

• The invariant REMARKS block. It suggests trying Get-Help with -Examples, -Detailed, and -Full, but doesn’t mention
-Parameter , which I happen to find especially useful.

• I expressed curiosity about why About help uses Short Description and Long Description in preference to comment-based help’s Synopsis and Description. Now I see that finding Short Description in the first five lines is a clue for the About parser. Sigh. It could modified to be either, you know.

• New and unexpected. Today I happened to create a comment-based help that included a numbered list, which I entered as follows, intending to clean up the indentation later.

Introductory line

1. Multi-line text that I
    entered into the file
    like this.
2. Second list item
    similarly

To my surprise, Get Help preserved my indentation within the list, whereas I was expecting to be annoyed by all the lines being pulled left. Not complaining at all, but what other kinds of lists preserve a hanging indent? Upper/lowercase letters? Various bullets? Etc. Documented anywhere?

May I assume that I can keep this whole issue open, pending some authoritative reply?

[sdwheeler]

The template specifies specific column numbers, and I wonder if this is a requirement for the parser or simply a suggestion.

If you don't indent to column 5, Get-Help doesn't find the information and doesn't display "Short Description" in the table view (as Synopsis). Unfortunately, this is the current state for the about_topics that we maintain. Our publishing pipeline doesn't handle the conversion from Markdown to plain text in a way that is compatible with these requirements. I am investingating a way to fix that.

• You write “Get-Help doesn't render markdown and never has.” OK, fine, but then all the official PowerShell help topics that display raw markdown should get updated. It’s confusing to read.

This is the editorial choice we made. We write our help in Markdown. The markdown is "compiled" into MAML (XML) and is used to create the HTML webpages. Our eventual goal is to be able to render markdown for help. There is no easy way to remove the markup.

• PowerShell-Docs style guide. Interesting and helpful collection of conventions. But in case you hadn’t noticed, it downright requires markdown for type names, class names, property names, etc.

This style guide is based on how WE write our docs, which are written in Markdown as I mentioned above.

• Example first line ‘PS > ‘. That is, whatever I put in the first line after an .EXAMPLE header gets the ‘PS > ‘ slapped in front. Bug, or feature?

It's a buggy feature of Get-Help. I don't like it. There are several quirks with the whole comment-based help implementation. You could file bugs in the source code repo. Many already have. There are no plans to fix any of these anytime soon.

• Notes indentation.
Why is it so deep?
Got me to wondering if there’s some undocumented feature of Notes involving heading levels.

I'm not sure what you mean by "so deep" or what specific indentation you are referring to. Can you provide an example?

• The invariant REMARKS block. It suggests trying Get-Help with -Examples, -Detailed, and -Full, but doesn’t mention -Parameter, which I happen to find especially useful.

File a bug/feature request in the source code repo.

• New and unexpected. Today I happened to create a comment-based help that included a numbered list, which I entered as follows, intending to clean up the indentation later.

Get-Help isn't processing the content. It copies the block of text as written.

May I assume that I can keep this whole issue open, pending some authoritative reply?

I intend to make some updates to the documentation based on our discussion here. I will close the issue once I have made the changes.

[sdwheeler]

Information about the About_ files can be found in https://learn.microsoft.com/powershell/scripting/developer/help/writing-help-for-windows-powershell-modules#types-of-module-help.

Though it lacks the information about the column number dependency. I will fix that.

[jaberenberg]

Responding for the request for indentation issue, here is a test.ps1 file exhibiting behavior that I will comment on after.

<#
    .SYNOPSIS
        Repeats whatever you tell it.
    
    .DESCRIPTION
        This function echoes its parameter back to you.

        1. First it does
           this
        2. And then
           it does that

    .EXAMPLE
        SimonSaysSay What
        What

    .EXAMPLE
        SimonSaysSay 'She sells seashells'
        She sells seashells

        Notice that the source help text does not contain 'PS > '

    .INPUTS
        None.  The function does not accept input from the pipeline.

    .OUTPUTS
        System.String

    .NOTES
        Additional information about the function go here.

    .LINK
        https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.5

    .LINK
        about_functions_advanced

    .NOTES
    This starts in column 5.

    1. This list starts in column 5
       and has continuation lines in column 8
    2. Here is more of
       the hanging indent list

        This line starts in column 8
            This line starts in column 12
This line starts in column 1

#>
function SimonSaysSay {
  [CmdletBinding(PositionalBinding=$false)]
    Param (
      # A string that you would like to see again.
      [Parameter(Position=0)]
      [String]$What
    )
  $What
} # SimonSaysSay

OK, and here I am dot sourcing the script

PS > . .\test.ps1
PS > SimonSaysSay what
what

And here is the help output with -full

PS > Get-Help SimonSaysSay =full

NAME
    SimonSaysSay

SYNOPSIS
    Repeats whatever you tell it.


SYNTAX
    SimonSaysSay [[-What] <String>] [<CommonParameters>]


DESCRIPTION
    This function echoes its parameter back to you.

    1. First it does
       this
    2. And then
       it does that


PARAMETERS
    -What <String>
        A string that you would like to see again.

        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
    None.  The function does not accept input from the pipeline.


OUTPUTS
    System.String


NOTES


        This starts in column 5.

        1. This list starts in column 5
           and has continuation lines in column 8
        2. Here is more of
           the hanging indent list

            This line starts in column 8
                This line starts in column 12
        This line starts in column 1

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

    PS > SimonSaysSay What
    What






    -------------------------- EXAMPLE 2 --------------------------

    PS > SimonSaysSay 'She sells seashells'
    She sells seashells

    Notice that the source help text does not contain 'PS > '





RELATED LINKS
    https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.5
    about_functions_advanced


PS > 

So my comments about the help output are as follows.

The lines in the Notes section are indented 8. All the other sections indent 4. Also, the Notes text starts two blank lines below its header.

The first line of each example starts 'PS > ' although that is not present in the input text.

Whatever the rules for the initial indent on each line may be, they are not immediately clear.

[sdwheeler]

The lines in the Notes section are indented 8. All the other sections indent 4. Also, the Notes text starts two blank lines below its header.

This is a bug in the formatting for help object. You can file an issue in the source code repo.

The first line of each example starts 'PS > ' although that is not present in the input text.

As I said previously, this is a feature that I don't like. It would take a code change to get rid of it.

Whatever the rules for the initial indent on each line may be, they are not immediately clear.

When the PowerShell help system parses the comments, it strips the leading whitespace from the content lines of each section. The number of characters to strip from each line is based on the number of whitespace characters on the first line of the content. That is the value stored in the object model.

When the object is output, the format system adds indentation. For whatever reason, the format of NOTES section is adding 2 blank lines and indents by 4 characters twice.

PS> $h = Get-Help -full SimonSaysSay
PS> $h | Get-Member

   TypeName: MamlCommandHelpInfo#FullView

Name          MemberType   Definition
----          ----------   ----------
Equals        Method       bool Equals(System.Object obj)
GetHashCode   Method       int GetHashCode()
GetType       Method       type GetType()
ToString      Method       string ToString()
alertSet      NoteProperty MamlCommandHelpInfo#alertSet alertSet=@{alert=System.Management.Automation.PSObject[]}
Category      NoteProperty string Category=Function
Component     NoteProperty object Component=null
description   NoteProperty psobject[] description=System.Management.Automation.PSObject[]
details       NoteProperty MamlCommandHelpInfo#details details=@{name=SimonSaysSay; description=System.Management.Auto…
examples      NoteProperty MamlCommandHelpInfo#examples examples=@{example=System.Management.Automation.PSObject[]}
Functionality NoteProperty object Functionality=null
inputTypes    NoteProperty MamlCommandHelpInfo#inputTypes inputTypes=@{inputType=@{type=@{name=None.  The function doe…
ModuleName    NoteProperty string ModuleName=
Name          NoteProperty string Name=SimonSaysSay
parameters    NoteProperty MamlCommandHelpInfo#parameters parameters=@{parameter=@{parameterValue=String; name=What; t…
relatedLinks  NoteProperty MamlCommandHelpInfo#relatedLinks relatedLinks=@{navigationLink=System.Management.Automation…
returnValues  NoteProperty MamlCommandHelpInfo#returnValues returnValues=@{returnValue=@{type=@{name=System.String}}}
Role          NoteProperty object Role=null
Synopsis      NoteProperty string Synopsis=Repeats whatever you tell it.
syntax        NoteProperty MamlCommandHelpInfo#syntax syntax=@{syntaxItem=@{parameter=@{parameterValue=String; name=Wh…
xmlns:command NoteProperty string xmlns:command=http://schemas.microsoft.com/maml/dev/command/2004/10
xmlns:dev     NoteProperty string xmlns:dev=http://schemas.microsoft.com/maml/dev/2004/10
xmlns:maml    NoteProperty string xmlns:maml=http://schemas.microsoft.com/maml/2004/10

The NOTES section information is in the alertSet property of the help object. The text of the section is in the alert property of alertSet.

PS> $h.alertSet | gm

   TypeName: MamlCommandHelpInfo#alertSet

Name        MemberType   Definition
----        ----------   ----------
Equals      Method       bool Equals(System.Object obj)
GetHashCode Method       int GetHashCode()
GetType     Method       type GetType()
ToString    Method       string ToString()
alert       NoteProperty psobject[] alert=System.Management.Automation.PSObject[]

The MamlCommandHelpInfo#alertSet type has its own formatting. You can see there are extra blank lines and the content is indented 4 characters.

PS> $h.alertSet



    This starts in column 5.

    1. This list starts in column 5
       and has continuation lines in column 8
    2. Here is more of
       the hanging indent list

        This line starts in column 8
            This line starts in column 12
    This line starts in column 1

The formatted alertSet property is getting wrapped inside of another 4 character indent. So it gets indented twice.

The content of alertSet.alert is not indented.

PS> $h.alertSet.alert

This starts in column 5.

1. This list starts in column 5
   and has continuation lines in column 8
2. Here is more of
   the hanging indent list

    This line starts in column 8
        This line starts in column 12
This line starts in column 1