Document optional titles in comment-based help examples - #13272
Marius Storhaug (MariusStorhaug) wants to merge 10 commits into
Conversation
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
There was a problem hiding this comment.
🔵 Needs a closer look
It documents a version-gated upstream feature whose final shipping version/behavior needs a human-confirmed pre-merge verification.
Pull request overview
This PR updates the PowerShell documentation set to describe the new optional .EXAMPLE <Title> syntax for comment-based help, including how it renders in Get-Help output and the compatibility impact on older PowerShell versions.
Changes:
- Documented optional inline
.EXAMPLEtitles and linked the syntax guidance to the keyword reference. - Added a runnable function example showing one titled and one untitled example, plus the expected
Get-Help -Examplesoutput. - Updated the PowerShell 7.7
about_Comment_Based_Helpreference to include the new.EXAMPLEtitle behavior and compatibility note.
File summaries
| File | Description |
|---|---|
| reference/docs-conceptual/developer/help/syntax-of-comment-based-help.md | Adds .EXAMPLE <Title> syntax mention and links to keyword details. |
| reference/docs-conceptual/developer/help/examples-of-comment-based-help.md | Adds a new Example 6 demonstrating titled vs untitled examples and Get-Help output. |
| reference/docs-conceptual/developer/help/comment-based-help-keywords.md | Expands .EXAMPLE keyword documentation with title syntax, rendering, and compatibility warning. |
| reference/7.7/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md | Updates 7.7 reference topic to describe optional example titles and links to the full example. |
Review details
- Files reviewed: 4/4 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
|
Learn Build status updates of commit 1ac0f29: ✅ Validation status: passed
For more details, please refer to the build report. |
|
Learn Build status updates of commit c5c9974: ✅ Validation status: passed
For more details, please refer to the build report. |
Sean Wheeler (sdwheeler)
added
hold-for-pr
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit f0ad8c8: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 66bc55f: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit cb0094e: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit abe9af4: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit a3b6432: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 2838a01: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit 7e6e36c: ✅ Validation status: passed
For more details, please refer to the build report. |
PoliCheck Scan ReportThe following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans. ✅ No issues foundMore information about PoliCheckInformation: PoliCheck | Severity Guidance | Term |
|
Learn Build status updates of commit be22dd9: ✅ Validation status: passed
For more details, please refer to the build report. |
PR Summary
Document the optional
.EXAMPLE <Title>syntax proposed in PowerShell/PowerShell#27387.Get-Help -Examples,-Detailed, and-Full.Ready for review. Merge depends on PowerShell/PowerShell#27387 being merged and the first supporting release being confirmed. The 7.7 wording is provisional. Defer the What's New entry until release inclusion is confirmed; the current article describes 7.7.0-preview.4, which does not include this feature. SDK reference publication should also include the additive
CommentHelpInfo.ExampleTitlesAPI; that reference is outside this repository.The example parses and returns both expected greetings on PowerShell 7.6.5, which also demonstrates the documented older-version help behavior. Titled help output is based on the upstream implementation; execution on a build containing the feature remains a pre-merge check. Markdownlint reports only four pre-existing findings in unchanged content: an undefined
09link in the keywords article and three overlong example lines in the syntax and examples articles.PR Checklist