Document optional titles in comment-based help examples

[Marius Storhaug (MariusStorhaug)]

PR Summary

Document the optional .EXAMPLE <Title> syntax proposed in PowerShell/PowerShell#27387.

• Describe inline titles in block and single-line comments, automatic example numbering, and rendering with Get-Help -Examples, -Detailed, and -Full.
• Add a runnable function with titled and untitled examples and the resulting example sections.
• Update the PowerShell 7.7 reference and shared comment-based help authoring guidance, with links to the complete example.
• Explain that PowerShell 7.6 and earlier discard the entire authored help block when the new syntax is used. Older versioned reference pages remain unchanged.

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.ExampleTitles API; 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 09 link in the keywords article and three overlong example lines in the syntax and examples articles.

PR Checklist

• Descriptive Title: This PR's title is a synopsis of the changes it proposes.
• Summary: This PR's summary describes the scope and intent of the change.
• Contributor's Guide: I have read the contributor's guide.
• Style: This PR adheres to the style guide.

[learn-build-service-prod]

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[learn-build-service-prod]

PoliCheck Scan Report

The 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 found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

[Copilot]

🔵 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 .EXAMPLE titles 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 -Examples output.
• Updated the PowerShell 7.7 about_Comment_Based_Help reference to include the new .EXAMPLE title 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-service-prod]

Learn Build status updates of commit 1ac0f29:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/7.7/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md	✅Succeeded	View (powershell-7.7)
reference/docs-conceptual/developer/help/comment-based-help-keywords.md	✅Succeeded	View (>=powershell-5.1)
reference/docs-conceptual/developer/help/syntax-of-comment-based-help.md	✅Succeeded	View (>=powershell-5.1)

For more details, please refer to the build report.

[learn-build-service-prod]

Learn Build status updates of commit c5c9974:

✅ Validation status: passed

File	Status	Preview URL	Details
reference/7.7/Microsoft.PowerShell.Core/About/about_Comment_Based_Help.md	✅Succeeded	View (powershell-7.7)
reference/docs-conceptual/developer/help/comment-based-help-keywords.md	✅Succeeded	View (>=powershell-5.1)
reference/docs-conceptual/developer/help/examples-of-comment-based-help.md	✅Succeeded	View (>=powershell-5.1)
reference/docs-conceptual/developer/help/syntax-of-comment-based-help.md	✅Succeeded	View (>=powershell-5.1)

For more details, please refer to the build report.