Skip to content

Comment-based help examples now support optional titles - #27387

Open
Marius Storhaug (MariusStorhaug) wants to merge 43 commits into
PowerShell:masterfrom
MariusStorhaug:feature/example-titles-in-comment-help
Open

Marius Storhaug (MariusStorhaug) wants to merge 43 commits into
PowerShell:masterfrom
MariusStorhaug:feature/example-titles-in-comment-help

Conversation

@MariusStorhaug

@MariusStorhaug Marius Storhaug (MariusStorhaug) commented May 1, 2026 •

Copy link
Copy Markdown

Comment-based help examples can now have an optional title. Write .EXAMPLE <Title> on one line, and Get-Help shows the title next to the example number. Help without titles works as before. Tools that read help, such as PlatyPS, can read the titles too.

Action is needed only if you want titles. Help that uses titles still loads and runs on older PowerShell versions, but those versions show no help for a block that uses .EXAMPLE <Title>. Plan for that before you adopt titles.

New: Titled examples in comment-based help

Before this change, text after .EXAMPLE on the same line was not valid. Get-Help silently dropped the whole help block. Now that text is the example title, in the same way that .PARAMETER <Name> takes its name on the same line. Titles also work with line comments (# .EXAMPLE Title). Get-Help -Examples, -Detailed, -Full and -ShowWindow all show the title.

To adopt titles, put the title on the .EXAMPLE line. Leave the line bare for an untitled example. You can mix both in one help block.

function Get-Report {
<#
    .SYNOPSIS
    Generates a report.

    .EXAMPLE Generating a summary report
    Get-Report -Type Summary

    .EXAMPLE
    Get-Report -Type Full
#>
    param([string]$Type)
}

Get-Help Get-Report -Examples then shows these headings:

-------------------------- EXAMPLE 1: Generating a summary report --------------------------
-------------------------- EXAMPLE 2 --------------------------
Scenario Result
Existing help with plain .EXAMPLE No change. Output is identical.
Existing help with text after .EXAMPLE on the same line Before: Get-Help dropped the help block. Now: the text is the title.
Help with titles, loaded on an older PowerShell The code loads and runs. Get-Help shows no help for that block. Document the minimum PowerShell version.
Proxy commands from ProxyCommand.GetHelpComments() Titles are kept.
PlatyPS Titled examples export to Markdown, YAML and MAML (tested with Microsoft.PowerShell.PlatyPS 1.0.3).

For optional depth, see the documentation PR: MicrosoftDocs/PowerShell-Docs#13272

Technical details
Related references

New: Tools can read example titles

Tools that read comment-based help, such as PlatyPS, documentation generators and formatters, can now get the title of each example. The help object from GetHelpContent() has a new property, ExampleTitles. It has the same length and the same order as Examples. An empty string means that the example has no title.

No action is needed for existing tools. Examples is unchanged. Read ExampleTitles only if your tool must show or export titles.

$ast = [System.Management.Automation.Language.Parser]::ParseFile($path, [ref]$null, [ref]$null)
$help = $ast.EndBlock.Statements[0].Body.GetHelpContent()
for ($i = 0; $i -lt $help.Examples.Count; $i++) {
    "Example $($i + 1): $($help.ExampleTitles[$i])"
}
Technical details
  • Tests check that ExampleTitles and Examples always have the same count.
Related references

Fixed: Generated proxy command help keeps a single example

When a function had exactly one example, ProxyCommand.GetHelpComments() left that example out of the generated help comments. The example is now kept. Output for functions with several examples does not change, and no action is needed.

Technical details
  • ProxyCommand.Tests.ps1 has a regression test for a function with exactly one example.

…into feature/example-titles-in-comment-help
… tests

- Revert CommentHelpInfo.Examples to ReadOnlyCollection<string>; add parallel ExampleTitles property per issue spec (non-breaking)
- Update HelpCommentsParser to maintain parallel _exampleTitles list
- Make ProxyCommand.ExtractExampleTitle culture-agnostic (anchor on dashes/colon, not the literal English word EXAMPLE)
- Fix \n vs backtick-n in ProxyCommand round-trip tests
- Add tests: line-comment titled examples, ExampleTitles count parity, title ending with dash, untitled-output regression
@MariusStorhaug Marius Storhaug (MariusStorhaug) changed the title 🚀 [Feature]: Comment-based help examples now support optional titles Comment-based help examples now support optional titles May 1, 2026
@MariusStorhaug

Copy link
Copy Markdown
Author

If this is interesting, ill continue with the other repos to align those with the added feature.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Adds support for optional titles on comment-based help examples using the .EXAMPLE <Title> syntax, and preserves those titles through XML generation and proxy help comment round-tripping.

Changes:

  • Extend comment-based help parsing and XML generation to capture/render optional .EXAMPLE titles.
  • Add a new CommentHelpInfo.ExampleTitles parallel collection and update GetCommentBlock() to round-trip titled examples.
  • Update ProxyCommand.GetHelpComments() to emit .EXAMPLE <title> when a user title can be recovered, and add Pester coverage for the new behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
src/System.Management.Automation/help/HelpCommentsParser.cs Captures .EXAMPLE <title> in the parser and appends titles to the generated example heading.
src/System.Management.Automation/engine/parser/ast.cs Adds CommentHelpInfo.ExampleTitles and updates GetCommentBlock() to emit .EXAMPLE <title> when present.
src/System.Management.Automation/engine/ProxyCommand.cs Extracts user titles from decorated MAML headings and emits .EXAMPLE <title> during proxy help comment generation.
test/powershell/Language/Scripting/ScriptHelp.ExampleTitles.Tests.ps1 New Pester coverage for titled .EXAMPLE parsing, round-trip via GetCommentBlock(), and backward compatibility.
test/powershell/engine/Api/ProxyCommand.Tests.ps1 Adds tests asserting ProxyCommand.GetHelpComments() preserves/emits titled examples and handles edge cases.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

…hen ProxyCommand title round-trip tests

- Updated the XML doc on ExtractExampleTitle to say ':' (matching the
  IndexOf(':') implementation) instead of the misleading ': '.
- Changed the existing round-trip assertion from Should -Not -BeNullOrEmpty
  (trivially true for all examples) to exact title equality comparison.
- Added a dedicated test 'ProxyCommand.GetHelpComments preserves custom
  example titles' that defines a function with titled and untitled examples,
  round-trips through GetHelpComments, and asserts the custom title text
  survives.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

@MariusStorhaug

Copy link
Copy Markdown
Author

Tested commit 74aba26f1 with Microsoft.PowerShell.PlatyPS 1.0.3. Basic titled examples already export successfully to Markdown, YAML, and MAML.

This exposed two existing title-preservation bugs in platyPS, addressed in PowerShell/platyPS#864. With that fix, all 10 sample example headings survive export unchanged.

The platyPS fix follows the same localization-independent principle: remove decorative borders without interpreting the example label. Unlike proxy comment generation, platyPS retains the complete numbered heading, so it does not split at : .

@MariusStorhaug

Copy link
Copy Markdown
Author

The companion documentation PR is ready for review: MicrosoftDocs/PowerShell-Docs#13272

It documents optional .EXAMPLE <Title> syntax, titled and untitled examples, Get-Help output, and compatibility with older PowerShell versions. The documentation targets 7.7 provisionally; merging it depends on this PR landing and confirmation of the first supporting release.

Marius Storhaug and others added 3 commits September 8, 2026 13:58
Remove anchored dash-and-space borders without depending on a fixed width. Preserve hyphens in custom titles and leave malformed borders unchanged.

Add regression coverage for border widths, required separator spaces, and title punctuation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Capture the custom title and outer borders in one non-backtracking regex.
Preserve existing untitled, localized, malformed-heading, and punctuation
behavior.

Add exact round-trip coverage for authored dash borders and internal
hyphens, including line-comment help.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@MariusStorhaug

Marius Storhaug (MariusStorhaug) commented Sep 8, 2026 •

Copy link
Copy Markdown
Author

Simplified the title extraction as suggested, in 24fef03.

ExtractExampleTitle now recovers the title in a single anchored match instead of a border match followed by a separate IndexOf(": ") scan:

Match titleMatch = Regex.Match(title, @"\A-+ .*?(?:: (?<title>.*?))? -+\z", RegexOptions.NonBacktracking);

The outer dash runs and the first : delimiter are handled in one step. RegexOptions.NonBacktracking is used because the equivalent backtracking pattern degrades badly on a malformed heading that has many : delimiters and no closing border; there is a regression case for that input.

Only the generated decoration is removed, so authored punctuation survives intact:

maml:title Emitted directive
-------- EXAMPLE 1: Authentication - As a User -------- .EXAMPLE Authentication - As a User
------ Example: --- Test - This is a title --- ------ .EXAMPLE --- Test - This is a title ---
--- EXAMPLE 1: Step 1: Initialize --- .EXAMPLE Step 1: Initialize
--- EXAMPLE 1 --- .EXAMPLE

Added round-trip coverage for internal hyphens and authored dash borders through both ProxyCommand.GetHelpComments and CommentHelpInfo.GetCommentBlock, plus cases for an empty title after the delimiter and the malformed-heading input above. Verified a real localized heading as well: under de-DE, BEISPIEL 1: --- Test - This is a title --- still yields .EXAMPLE --- Test - This is a title ---.

Both focused files pass locally via Start-PSPester: 239 passed, 0 failed.

Also merged current master (5bbe60c). The two LocProject.Tests.ps1 failures in the previous CI run are unrelated to this PR and reproduce on a clean master checkout with no changes applied:

[-] Validate LocItems in LocProject.json
      Expected: '.pipelines\store\PDPs\PDP\en-US\'
      But was:  '.pipelines\store\PDPs\PDP\'
[-] Validate total resource count
      Expected 150, but got 151.

The .pipelines\store\PDPs\PDP\en-US\PDP.xml entry added in #27966 sets OutputPath to the parent of the en-US folder, which the first assertion rejects, and it is counted in LocItems even though the count is compared against the number of .resx files under src. Tracked separately in #27987.

Marius Storhaug and others added 4 commits September 9, 2026 08:00
Assert title and body alignment for titled-first, untitled-first, and
three-example interleavings through both GetCommentBlock and proxy comment
generation.

Exercise titles containing hyphens and dash borders next to untitled
examples, where a misaligned index would otherwise go unnoticed.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Add fully titled and fully untitled three-example cases so the layout
permutations span both uniform ends alongside the interleaved ones.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Trim the dash border before the first space and after the last space using
index scans over spans, then split at the first ": " delimiter. Behavior is
unchanged, so authored hyphens and dash borders are still preserved.

Removes the regular expression and its NonBacktracking dependency, which was
only needed to bound backtracking on malformed headings.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Use Trim('-', ' ') to remove the generated dash border, then split at the
first ": " delimiter. A proxy-generated title therefore cannot begin or end
with a dash, and a heading without the delimiter carries no title.

The comment parser is unchanged, so authored titles still round-trip verbatim
through CommentHelpInfo.GetCommentBlock.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@microsoft-github-policy-service

Copy link
Copy Markdown
Contributor

This pull request has been automatically marked as Review Needed because it has been there has not been any activity for 7 days.
Maintainer, please provide feedback and/or mark it as Waiting on Author

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

Labels

CL-General Indicates that a PR should be marked as a general cmdlet change in the Change Log PowerShell-Docs needed The PR was reviewed and a PowerShell Docs update is needed Review - Needed The PR is being reviewed WG-Interactive-HelpSystem help infrastructure and formatting of help WG-Reviewed A Working Group has reviewed this and made a recommendation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Supporting Titles in Comment-Based Help Examples for script-based functions

6 participants