PowerShell: Get-Help does not recognize documentation comments in PS 7.2.3
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
When there are comments adjacent to documentation comments, documentation comments are not recognized by Get-Help
. This doesn’t work:
# Regular comment
<#
.SYNOPSIS
My documentation.
#>
When an empty line is added between these comments, Get-Help
works correctly. This works:
# Regular comment
<#
.SYNOPSIS
My documentation.
#>
Powershell version: 7.2.3 Windows version: 11 File encoding: UTF8 (no BOM) File endings: LF
For a demo, save the following file as BugDemo.ps1
:
# This comment makes the documentation comments below stop being recognized by Get-Help.
# Add an empty line below this comment (in line 3) and Get-Help works well again.
<#
.SYNOPSIS
Says hi.
.DESCRIPTION
Greets you politely.
.PARAMETER name
Your name.
#>
function SayHi
{
[OutputType([void])]
param
(
[Parameter(mandatory=$true, position=0, valueFromPipeline=$true)]
[string]
$name
)
Write-Host "Hi, $name! Nice to meet you!"
}
SayHi Fred
Get-Help SayHi
Expected behavior
PS> ./BugDemo.ps1
Hi, Fred! Nice to meet you!
NAME
SayHi
SYNOPSIS
Says hi.
SYNTAX
SayHi [-name] <String> [<CommonParameters>]
DESCRIPTION
Greets you politely.
RELATED LINKS
REMARKS
To see the examples, type: "Get-Help SayHi -Examples"
For more information, type: "Get-Help SayHi -Detailed"
For technical information, type: "Get-Help SayHi -Full"
Actual behavior
PS> ./BugDemo.ps1
Hi, Fred! Nice to meet you!
NAME
SayHi
SYNTAX
SayHi [-name] <string> [<CommonParameters>]
ALIASES
None
REMARKS
None
Error details
No response
Environment data
PS> $PsVersionTable
Name Value
---- -----
PSVersion 7.2.3
PSEdition Core
GitCommitId 7.2.3
OS Microsoft Windows 10.0.22000
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
About this issue
- Original URL
- State: closed
- Created 2 years ago
- Comments: 17 (7 by maintainers)
I think this has been the same over the whole life of comment based help.
The rule seems to be
Although inserting a comment before a comment shouldn’t change things, the combination of allowing the comment based help to be split, and quick and simple recognition of the help text leads to what we have.