Get-Help shows incorrect spacing and unwanted prefixes for first line of .EXAMPLE text

[daverayment]

Prerequisites

• Write a descriptive title.
• Make sure you are able to repro it on the latest released version
• Search the existing issues.
• Refer to the FAQ.
• Refer to Differences between Windows PowerShell 5.1 and PowerShell.

Steps to reproduce

I am writing a PowerShell module and adding help text for each of my exported cmdlets.

Several of my commands include multi-line examples, showing the command usage and example output, e.g.:

.EXAMPLE
PS> $devices = Get-MTPDeviceList
PS> if ($devices) { $devices[0].Name }
"My Phone"

.EXAMPLE
# Some explanatory text about the example.
PS> Get-MTPDeviceList

Name        Type
----        ----
Some Phone  Mobile Phone

I have tested my module in both Visual Studio Code's PowerShell terminal and also a separate instance of PowerShell in Terminal. When calling Get-Help Get-MTPDeviceList with switches that show example text (e.g. -Full or -Examples), the formatting of the displayed examples text is incorrect.

Specifically:

1. Any leading spaces between the "PS>" and the rest of the string on the first line is removed.
2. If the first line of an example is a comment (with or without a leading #), the text "PS >" is inserted before it.

Expected behavior

The following output should be displayed in the examples section when Get-Help -Full is called:

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

    PS> $devices = Get-MTPDeviceList
    PS> if ($devices) { $devices[0].Name }
    "My Phone"






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

    # Some explanatory text about the example.
    PS> Get-MTPDeviceList

    Name        Type
    ----        ----
    Some Phone  Mobile Phone

Actual behavior

The following is output. Note the removal of the space character in the first line of the first example and the insertion of the text "PS >" in the first line of the second example.

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

    PS>$devices = Get-MTPDeviceList
    PS> if ($devices) { $devices[0].Name }
    "My Phone"






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

    PS > # Some explanatory text about the example.
    PS> Get-MTPDeviceList

    Name        Type
    ----        ----
    Some Phone  Mobile Phone

Error details

No response

Environment data

Name                           Value
----                           -----
PSVersion                      7.4.2
PSEdition                      Core
GitCommitId                    7.4.2
OS                             Microsoft Windows 10.0.22631
Platform                       Win32NT
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0…}
PSRemotingProtocolVersion      2.3
SerializationVersion           1.1.0.1
WSManStackVersion              3.0

Visuals

No response

[237dmitry]

I do not view PS> in cmdlet's help examples...

------------- Example 1: Get the current directory ------------

Get-Item .

Directory: C:\

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
d----         7/26/2006  10:01 AM            ps-test


---- Example 2: Get all the items in the current directory ----

Get-Item *

Directory: C:\ps-test

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
d----         7/26/2006   9:29 AM            Logs
d----         7/26/2006   9:26 AM            Recs
-a---         7/26/2006   9:28 AM         80 date.csv
-a---         7/26/2006  10:01 AM         30 filenoext
-a---         7/26/2006   9:30 AM      11472 process.doc
-a---         7/14/2006  10:47 AM         30 test.txt


------- Example 3: Get the current directory of a drive -------

Get-Item C:

# and so on

As a workaround you can use `u{2800} instead of `u{0020}

[daverayment]

@237dmitry Your examples do not correspond to the details I provided in the Steps to Reproduce section above. The specific text formatting is significant, otherwise the issue will not present itself.

I can provide cut-down versions of the .psm1 and .psd1 files I am using, if that would help.

[mklement0]

@237dmitry, the issue is about comment-based help, whereas built-in cmdlets come with external, MAML-based help files (though the discrepancy in the resulting behavior is surprising).

@daverayment:

Here's how things currently work:

• The first line - only - after .EXAMPLE is assumed to be the example command, and it is prefixed with PS > by default - even if you try to provide a comment as the first line.

• If you try to provide your own prefix, PowerShell retains it, but without preserving whitespace after > - I'd say that's a bug.

• Anything after the first line is retained as-is.

---

Thus:

• Place comments describing the example after the first line (and after a line showing sample output).

• If you're not happy with the automatically applied PS > prefix (which you'd have to replicate explicitly in subsequent lines): As a workaround for the bug, you can use @237dmitry's suggestion to embed a literal [char] 0x2800 in lieu of space(s) after the >: this character will render like a space in terminals, but won't be trimmed by PowerShell.

[237dmitry]

I can provide cut-down versions

I tried simple function and it reproduces your issue. Workaround:

[daverayment]

Thank you both.

The workaround from @237dmitry does not work for me without using the special Unicode character for the space; otherwise, any spaces are removed. So:

PS>Something

instead of:

PS> Something

The default behaviour, as detailed by @mklement0, is problematic for a number of reasons:

1. Auto-adding the PS > is inconsistent with the in-built cmdlet's examples, which are all presented un-prefixed.
2. Auto-adding the PS > conflicts directly with all the examples on Microsoft's about Comment Based Help help page. All the examples in that guide have PS> present as prefixes to each of the example commands. Note the lack of space between the PS and >. This is the guide I followed when creating my own function's documentation.
3. It means developers cannot provide comments before the command. I recognise from the guide and @mklement0 's advice that the intention is for comments and descriptions to be after the command example itself, so I'm happy to change my examples to fit this pattern, but it still feels a bit restrictive. This is especially galling because the in-built commands have additional info in the header for each example:

------- Example 3: Display more information for a cmdlet -------

    Get-Help Format-Table -Detailed
    Get-Help Format-Table -Full

All we get for a header is the example number, e.g. -----EXAMPLE 1-----. We should be able to produce help documentation which is consistent with that for the built-in cmdlets.

4. It makes multi-line examples more difficult to document, because the developer has to treat the first line differently.

The whitespace-eating bug is annoying. I'm not keen on embedding special characters to get around this issue, but appreciate the advice. The other option is to leave out the PS> prefix on the first line and rely on Get-Help adding the prefix itself for that line only, but again, this feels like a workaround for something which should not be happening. If MS change things around to remove the auto-addition of the prefix (which I hope they do!), this would again introduce inconsistency between the first line and subsequent ones if this workaround had been applied.

In conclusion, I think a reasonable expectation from running Get-Help is that the comments are reproduced verbatim, with any formatting introduced by the cmdlet being merely cosmetic, such as the section headers. This is especially important for sections which include code.

For this reason, I think the PS > prefix should not be auto-added in future versions.

If the prefix remains in future versions, it should obviously be documented, and not left as a surprise for the developer 😀

[krzydoug]

All we get for a header is the example number, e.g. -----EXAMPLE 1-----. We should be able to produce help documentation which is consistent with that for the built-in cmdlets.

I always wondered why there wasn't a way to add additional details after .EXAMPLE. That'd be nice

Wishful thinking

Function Test-Function {
    <#
    .EXAMPLE Some additional details
    Test-Function
    <#
}

[theJasonHelmick]

Thank you @daverayment for this issue. The Interactive working group had reviewed this and agrees there is a bug in the comment based help causing the space.