Repository navigation
Comment-based help examples now support optional titles - #27387
Marius Storhaug (MariusStorhaug) wants to merge 43 commits into
Conversation
…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
…is not blocked by an unrelated pre-existing failure in ScriptHelp.Tests.ps1
…fix and function-scope isolation
|
If this is interesting, ill continue with the other repos to align those with the added feature. |
There was a problem hiding this comment.
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
.EXAMPLEtitles. - Add a new
CommentHelpInfo.ExampleTitlesparallel collection and updateGetCommentBlock()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. |
…ng comment in ExtractExampleTitle
…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.
|
Tested commit 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 |
|
The companion documentation PR is ready for review: MicrosoftDocs/PowerShell-Docs#13272 It documents optional |
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>
…les-in-comment-help
|
Simplified the title extraction as suggested, in 24fef03.
Match titleMatch = Regex.Match(title, @"\A-+ .*?(?:: (?<title>.*?))? -+\z", RegexOptions.NonBacktracking);The outer dash runs and the first Only the generated decoration is removed, so authored punctuation survives intact:
Added round-trip coverage for internal hyphens and authored dash borders through both Both focused files pass locally via Also merged current The |
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>
|
This pull request has been automatically marked as Review Needed because it has been there has not been any activity for 7 days. |
Comment-based help examples can now have an optional title. Write
.EXAMPLE <Title>on one line, andGet-Helpshows 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
.EXAMPLEon the same line was not valid.Get-Helpsilently 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,-Fulland-ShowWindowall show the title.To adopt titles, put the title on the
.EXAMPLEline. Leave the line bare for an untitled example. You can mix both in one help block.Get-Help Get-Report -Examplesthen shows these headings:.EXAMPLE.EXAMPLEon the same lineGet-Helpdropped the help block. Now: the text is the title.Get-Helpshows no help for that block. Document the minimum PowerShell version.ProxyCommand.GetHelpComments()For optional depth, see the documentation PR: MicrosoftDocs/PowerShell-Docs#13272
Technical details
ScriptHelp.ExampleTitles.Tests.ps1, and additions toProxyCommand.Tests.ps1. They cover titled, untitled and mixed examples, titles with colons and dashes, line comments, and round trips.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 asExamples. An empty string means that the example has no title.No action is needed for existing tools.
Examplesis unchanged. ReadExampleTitlesonly if your tool must show or export titles.Technical details
ExampleTitlesandExamplesalways 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.ps1has a regression test for a function with exactly one example.