Skip to content

Get-Help ignores non-standard comment-based help keywords, so custom boilerplate sections are silently dropped from -Full output. #28289

Open

Description

Summary of the new feature / enhancement

Get-Help silently drops non-standard keywords from comment-based help blocks. Teams that standardize their script headers with custom sections (for example .RISK CLASSIFICATION, .ENVIRONMENT ASSUMPTIONS, .REQUIREMENTS, .VERSION) cannot display them through Get-Help without opening the file.

Currently, when you run get-help on a script it only parses the boilerplate values it is aware of like .NOTES, .PARAMETER, .DESCRIPTION, and so on. I am hoping we can get an extra flag added to get-help to get other fields and display that in a formatted manner to screen.

NOTE - This is a display feature, not a validation feature. Teams should enforce their own boilerplate standards with tooling, as ours does.

Proposed technical implementation details (optional)

Add an -IncludeUnknown switch to Get-Help. When specified, Get-Help parses the first comment-based help block in the script (<# to #>), and only the first comment-based help block in the script, and renders every keyword it doesn’t recognize.

-IncludeUnknown alone shows only the unknown sections.
-IncludeUnknown combined with -Full shows the standard output followed by the unknown sections.
Without -IncludeUnknown, behavior is unchanged, so this is non-breaking.
Unknown sections render in file order after the standard sections, with the heading kept exactly as written (for example .RISK CLASSIFICATION), content indented beneath it, and internal blank lines preserved.
If first comment block contains no section headers, then nothing is added by adding include unknown.

Sample code:
<#
.REQUIREMENTS
- Powershell 7
#>

Current behavior - .REQUIREMENTSare not shown.
New behavior - if -IncludeUknown is present, .REQUIREMENTS are shown when get-help is called.

NOTE - This is a display feature, not a validation feature. Teams should enforce their own boilerplate standards with tooling, as ours does.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Issue-Enhancementthe issue is more of a feature request than a bugNeeds-TriageThe issue is new and needs to be triaged by a work group.WG-Interactive-HelpSystemhelp infrastructure and formatting of help

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions