I stumbled across some issues with the .EXAMPLEs in in Comment Based Help. So, let’s jump right in and take a dummy function with some comment based help.
function Test-Something {
Test-Something
Explanation of what the example does
#>
[cmdletbinding()]
param(
[string]$Param1,
[string]$Param2
)
Write-Verbose 'something would happen here..' -Verbose
}
When you run help Test-Something -full it produces this output:
NAME
Test-Something
SYNOPSIS
dummy function
SYNTAX
Test-Something [[-Param1] ] [[-Param2] ] []
DESCRIPTION
dummy function that doesn't do anything
PARAMETERS
-Param1
Required? false
Position? 1
Default value
Accept pipeline input? false
Accept wildcard characters? false
-Param2
Required? false
Position? 2
Default value
Accept pipeline input? false
Accept wildcard characters? false
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 C:\>Test-Something
Explanation of what the example does
RELATED LINKS
Nice and simple, it works almost exactly as expected.
Here is the list of things I discovered.
- There will always be a blank line inserted after the first line of the .EXAMPLE text. (already demonstrated in the above example.)
- There will always be something that looks like a prompt in the first line of the help.
- The second line of data will always be left aligned. This doesn’t sound like much at first.. but as you will see later, it can be a very large problem.
- Adding anything to the text of any .EXAMPLE line prevents any of the examples from being displayed.
Blank line inserted
Here is another example and the results..
Line1 of Example Text
Line2 of Example Text
#>
# Output
-------------------------- EXAMPLE 2 --------------------------
PS C:\>
Line1 of Example Text
Line2 of Example Text
You can see how the blank line is inserted, even though the original .EXAMPLE section doesn’t contain a blank line.
Powershell prompt forcibly inserted
Let’s take the above example, and remove the prompt that we typed. You can see that is was the first thing forcibly inserted.
# Output -------------------------- EXAMPLE 3 -------------------------- PS C:\>Line3 of Example Text Line4 of Example text
Notice that Line3 has a default powershell prompt inserted right before the text, without a new line.
If we have something that looks like a prompt, then it will not be forcibly inserted. From some basic testing, it looks like the presence of the > character is what determines when a prompt is inserted and when it is not. I haven’t tested this exhaustively. Example 4 does not contain a >, while Example 5 is only a >.
# Output -------------------------- EXAMPLE 4 -------------------------- PS C:\>PS C:] Line5 of ExampleText Line6 of ExampleText
Line7 of ExampleText
Line8 of ExampleText
#>
# Output
-------------------------- EXAMPLE 5 --------------------------
>
Line7 of ExampleText
Line8 of ExampleText
2nd line is always left-aligned
This is the problem that was the instigator for this entire article. Example 6 will just show the issue, and then Example 7 & Example 8 will show why this is a problem.
This line (the 2nd) is indented 12 spaces
#>
# Output
-------------------------- EXAMPLE 6 --------------------------
>
This line (the 2nd) is indented 12 spaces
Example 7 shows some basic column output in the help.
Name Value
---- -----
Var1 0
Var2 1
Var3 2
Var4 3
#>
# Output
-------------------------- EXAMPLE 7 --------------------------
>
Name Value
---- -----
Var1 0
Var2 1
Var3 2
Var4 3
Example 8 is where the problem really shows, and this where I discovered the problem (and it led to the rest of this discovery of issues). I wrote a function that produced columns that were aligned in the center. This first version shows what would be expected.
Name Value
---- -----
MiscVar1 0
MiscellaneousVar2 1
SomeVar3 2
Variable4 3
#>
# This is the expected output
-------------------------- EXAMPLE 8 --------------------------
>
Name Value
---- -----
MiscVar1 0
MiscellaneousVar2 1
SomeVar3 2
Variable4 3
But.. that’s not the way this works unfortunately. Here is the real output:
-------------------------- EXAMPLE 8 --------------------------
>
Name Value
---- -----
MiscVar1 0
MiscellaneousVar2 1
SomeVar3 2
Variable4 3
A blank line is inserted as expected, and the 2nd actual line is forcibly left-aligned. I won’t put all the examples here, but as long as the 2nd line is preceded by a blank line or non-printable character, then it will always forcibly left align, which makes these semi-center aligned columns impossible to line up correctly. The only way I have found to make that column header line up is to insert some sort of printable character as the 2nd line of data. This will always be left aligned, and prevents the header line from being forced to the left. In this example, I used Alt+0254 (þ) as the printable character.
þ
Name Value
---- -----
MiscVar1 0
MiscellaneousVar2 1
SomeVar3 2
Variable4 3
#>
# Output
-------------------------- EXAMPLE 9 --------------------------
>
þ
Name Value
---- -----
MiscVar1 0
MiscellaneousVar2 1
SomeVar3 2
Variable4 3
Missing .EXAMPLE entries
This was just an idle test while writing this, and I thought it was worth mentioning. The .PARAMETER entries take a word right next to them which helps the display. I tried adding a word next to the .EXAMPLE entry just to see what would happen. And through some testing, I found out it doesn’t matter which .EXAMPLE you add a word to it, all of the example entries are suppressed. Here are the examples as I’ve typed them. I added the word Modified to line 25.
Test-Something
Explanation of what the example does
.EXAMPLE
PS C:\>
Line1 of Example Text
Line2 of Example Text
.EXAMPLE
Line3 of Example Text
Line4 of Example text
.EXAMPLE
PS C:]
Line5 of ExampleText
Line6 of ExampleText
.EXAMPLE
>
Line7 of ExampleText
Line8 of ExampleText
.EXAMPLE Modified
>
This line (the 2nd) is indented 12 spaces
.EXAMPLE
Name Value
---- -----
Var1 0
Var2 1
Var3 2
Var4 3
.EXAMPLE
>
Name Value
---- -----
MiscVar1 0
MiscellaneousVar2 1
SomeVar3 2
Variable4 3
.EXAMPLE
>
þ
Name Value
---- -----
MiscVar1 0
MiscellaneousVar2 1
SomeVar3 2
Variable4 3
#>
# Output
NAME
Test-Something
SYNTAX
Test-Something [[-Param1] ] [[-Param2] ] []
PARAMETERS
-Param1
Required? false
Position? 0
Accept pipeline input? false
Parameter set name (All)
Aliases None
Dynamic? false
-Param2
Required? false
Position? 1
Accept pipeline input? false
Parameter set name (All)
Aliases None
Dynamic? false
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
ALIASES
None
REMARKS
None
And as you can see, there are no examples displayed anymore, and the last section header isn’t LINKS anymore, it is REMARKS.
David F.
David R. Figueroa II 