PowerShell: Get-Help does not recognize documentation comments in PS 7.2.3

Prerequisites

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

BugDemo.ps1.txt

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)

Most upvoted comments

I think this has been the same over the whole life of comment based help.

The rule seems to be

  1. Comments before the function declaration are merged… If the result starts with .Synopis, .Description, etc it is treated as help text and help inside the function is ignored. (white space around comments and before the first . is ignored).
  2. If there is no valid comment based help before the function, comments at the start of the block (before any [cmdletbinding()] or similar) are merged If the result starts with .Synopis, .Description, etc it is treated as help text and any help at the end of the block is ignored.
  3. If 1 & 2 don’t provide help, comments at the end of the block are merged If the result starts with .Synopis, .Description, etc it is treated as help text
  4. For a parameter if no help is defined by 1,2 or 3comment(s) on the parameter (merged if there are 2 or more) become its help.

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.