如何在PowerShell注释式帮助中设置示例主题？

你想要复刻系统cmdlet（比如Get-ChildItem）的示例标题格式，也就是类似--- Example 1: Get child items from a file system directory ---的样式，在注释式帮助里是可以实现的，之前的尝试失败大概率是格式不符合规范导致的。

正确的实现方式 #

在.EXAMPLE关键字后直接跟上示例主题文本，换行后编写示例命令和说明即可，示例代码如下：

function Test-CustomHelp {
    <#
    .SYNOPSIS
    演示带主题的注释式帮助示例
    .EXAMPLE
    获取指定目录下的所有子项
    Test-CustomHelp -TargetPath "C:\Windows\System32"
    执行此命令会列出目标目录下的所有文件和子目录
    #>
    param(
        [string]$TargetPath
    )
    Get-ChildItem -Path $TargetPath
}

执行Get-Help Test-CustomHelp -Examples，输出会自动生成带主题的分隔式标题：

--- Example 1: 获取指定目录下的所有子项 ---
Test-CustomHelp -TargetPath "C:\Windows\System32"

执行此命令会列出目标目录下的所有文件和子目录

你之前尝试的问题分析 #

• 方法1（.EXAMPLE后加文本导致示例被省略）：大概率是格式错误，比如.EXAMPLE和主题文本之间有多余空行、主题文本后没有紧跟示例命令，或者注释块的缩进/换行不符合PowerShell的解析规则；
• 方法2（先写主题行出现PS>前缀）：PowerShell会把单独的主题行识别成示例命令的一部分，因此自动加上了PS>提示符；
• 方法3（注释放最后无内置分隔）：这种写法只是把说明放在了命令后面，没有利用.EXAMPLE的内置格式解析逻辑，所以无法生成标准的主题分隔标题。

补充说明 #

虽然微软官方文档对这个细节的描述不够清晰，但这种写法是PowerShell注释式帮助的标准支持用法，只要保证.EXAMPLE、主题文本、示例命令之间的格式连贯（无多余空行、缩进统一），就能正常生成带主题的示例标题。

内容的提问来源于stack exchange，提问作者Dan Solovay