Comment-based help examples can now carry an optional title using the .EXAMPLE Title text syntax, mirroring the inline pattern already used by .PARAMETER <Name>. Previously, putting any text on the same line as .EXAMPLE fell through to an unhandled default: case in the parser and silently discarded the entire help block — now that text is captured as the example's title and rendered alongside the auto-generated heading. Examples without titles continue to work exactly as before, so no existing help content is affected.

• Fixes Supporting Titles in Comment-Based Help Examples for script-based functions #23966
• Related: Get-Help shows incorrect spacing and unwanted prefixes for first line of .EXAMPLE text #23814 (heading spacing on first line of .EXAMPLE body)
• Related: PlatyPS#627 — unblocks PlatyPS consuming titled examples

New: Titled examples in comment-based help

Authors can now give each example a meaningful name on the same line as the .EXAMPLE keyword:

function Show-Example {
<#
    .SYNOPSIS
    Demonstrates titled and untitled examples.

    .EXAMPLE Retrieving an item from a directory
    Get-Item -Path C:\Temp

    Retrieves the item at C:\Temp.

    .EXAMPLE Listing files in a folder
    Get-ChildItem -Path C:\Temp

    Lists all files and folders in C:\Temp.

    .EXAMPLE
    Get-Process

    Gets all running processes (untitled — still works as before).
#>
    param()
}

Get-Help Show-Example -Examples renders titles alongside the auto-generated number, matching the format MAML-based help has always used for compiled cmdlets:

-------------------------- EXAMPLE 1: Retrieving an item from a directory --------------------------

Get-Item -Path C:\Temp

Retrieves the item at C:\Temp.

-------------------------- EXAMPLE 2: Listing files in a folder --------------------------

Get-ChildItem -Path C:\Temp

Lists all files and folders in C:\Temp.

-------------------------- EXAMPLE 3 --------------------------

Get-Process

Gets all running processes (untitled — still works as before).

Line-comment syntax (# .EXAMPLE Title) is supported as well.

New: CommentHelpInfo.ExampleTitles public property

External tools (PlatyPS, doc generators, formatters) can now read titles via a new public property on CommentHelpInfo:

public ReadOnlyCollection<string> ExampleTitles { get; internal set; }

ExampleTitles runs in parallel with the existing Examples collection — same length, same index mapping. An empty string entry means that example has no title.

var help = scriptBlockAst.GetHelpContent();
for (int i = 0; i < help.Examples.Count; i++)
{
    string title = help.ExampleTitles[i];
    string body  = help.Examples[i];
    if (!string.IsNullOrEmpty(title))
        Console.WriteLine($"EXAMPLE {i + 1}: {title}");
    else
        Console.WriteLine($"EXAMPLE {i + 1}");
    Console.WriteLine(body);
}

Round-trip preserved

Both serializers retain titles when regenerating comment-based help:

• CommentHelpInfo.GetCommentBlock() emits .EXAMPLE <title> when the title is non-empty, and .EXAMPLE on its own line when empty.
• ProxyCommand.GetHelpComments() reconstructs the user-supplied title from the decorated MAML heading via a new culture-agnostic helper (ExtractExampleTitle) that anchors on the dash-padding and : separator rather than the literal English word EXAMPLE — so it works under any UI culture.

Backward compatibility

Fully backward compatible:

• .EXAMPLE with no trailing text continues to behave exactly as before.
• The existing CommentHelpInfo.Examples property is unchanged (still ReadOnlyCollection<string> of bodies). ExampleTitles is purely additive.
• Existing comment-based help across the ecosystem renders identically — the only observable difference is that .EXAMPLE <text> no longer breaks the help block.

Out of scope

These follow-ups are tracked in the linked issue and need separate work in other repositories:

• about_Comment_Based_Help and the developer authoring guide in MicrosoftDocs/PowerShell-Docs
• PlatyPS consuming the new ExampleTitles property (#627)
• TextMate grammar updates in vscode-powershell and EditorSyntax so .EXAMPLE <Title> is recognized as a directive keyword the same way .PARAMETER <Name> is

Technical Details

Files changed:

• src/System.Management.Automation/help/HelpCommentsParser.cs — Added a new case "EXAMPLE" to the Groups[3].Success == true branch of AnalyzeCommentBlock that captures match.Groups[3].Value.Trim() into a new parallel List<string> _exampleTitles field, then collects the body via GetSection(). The existing case "EXAMPLE" in the no-arguments branch appends an empty string to _exampleTitles to keep the title and body indices aligned. The XML-building section conditionally appends : <title> to the EXAMPLE N heading when the title is non-empty. After parsing, _sections.ExampleTitles is assigned as a ReadOnlyCollection<string>.
• src/System.Management.Automation/engine/parser/ast.cs — Added the new ReadOnlyCollection<string> ExampleTitles { get; internal set; } property on CommentHelpInfo. Updated GetCommentBlock() to emit .EXAMPLE <title> when ExampleTitles[index] is non-empty, and .EXAMPLE on its own line otherwise. The existing Examples property type is unchanged — the design is intentionally a parallel collection, not a redesign of Examples, so the public API stays binary- and source-compatible.
• src/System.Management.Automation/engine/ProxyCommand.cs — Updated GetHelpComments to emit .EXAMPLE <title> when the underlying MAML title contains a user-supplied portion. Added the private ExtractExampleTitle helper that recovers the user title from the decorated MAML heading by anchoring on the dash-padding and the : separator, deliberately avoiding the literal word EXAMPLE so the logic remains correct under non-English UI cultures.
• test/powershell/Language/Scripting/ScriptHelp.Tests.ps1 — Added Pester coverage for: titled examples (verifying $help.examples.example.title), mixed titled/untitled examples, untitled-output regression (identical to current rendering), GetCommentBlock() round-tripping, regression test for the previous default: return false parser bug, line-comment syntax (# .EXAMPLE Title), edge cases (titles containing colons and dashes, titles ending with a dash), and a parity assertion that Examples.Count == ExampleTitles.Count.
• test/powershell/engine/Api/ProxyCommand.Tests.ps1 — Added round-trip tests for ProxyCommand.GetHelpComments with titled examples.

Implementation plan progress (from #23966):

• ✅ Parser changes — done
• ✅ Data model changes — done (parallel ExampleTitles collection; non-breaking)
• ✅ XML generation changes — done
• ✅ Round-trip serialization (GetCommentBlock + ProxyCommand.GetHelpComments + culture-agnostic ExtractExampleTitle) — done
• ✅ Tests — done
• ⬜ PowerShell-Docs updates — separate PR
• ⬜ PlatyPS update — separate PR (#627)
• ⬜ vscode-powershell / EditorSyntax grammar updates — separate PRs

Design history. An earlier revision changed CommentHelpInfo.Examples to ReadOnlyCollection<KeyValuePair<string, string>> to carry title and body together. That was reverted in commit 38f9720 based on review feedback to keep the public API non-breaking — the parallel ExampleTitles collection delivers the same capability without altering the existing Examples signature.

PR Checklist

• PR has a meaningful title
• Summarized changes
• Change is not breaking
• Make sure all .h, .cpp, .cs, .ps1 and .psm1 files have the correct copyright header
• Tests added/passed
• Documentation updates — tracked separately for PowerShell-Docs (see "Out of scope" above)
• Backward compatible
• User-facing cmdlet changes are documented — N/A, no cmdlet changes (parser/help engine only)