powershell 设置基于注解的帮助示例的主题

6qqygrtg 于 2023-05-22 发布在 Shell

关注(0)|答案(1)|浏览(211)

使用基于注解的帮助时，是否可以设置示例主题？
Get-Help Get-ChildItem -Examples的输出包含示例标题中的主题文本：

--- Example 1: Get child items from a file system directory ---

我想知道是否可以用基于注解的帮助来复制这种格式。
我尝试了以下语法：
1.在.EXAMPLE关键字之后放置文本。
函数Get-Example 1 { # .Example测试说明# Get-Example #样本输出。}
这导致该示例被省略。

PS > Get-Help Get-Example1 -Examples

NAME
    Get-Example1

ALIASES
    None

REMARKS
    None

1.把主题放在第一位
函数Get-Example 2 { # .EXAMPLE #测试说明# Get-Example #样本输出}
这会导致标题以PS>为前缀

PS > get-help Get-Example2 -Examples

NAME
    Get-Example2

SYNOPSIS

-------------------------- EXAMPLE 1 --------------------------

PS > Test description
Get-Example
Sample output

1.把评论放在最后：

function Get-Example3
    {
       # .EXAMPLE
       # Get-Example
       #
       # Sample output
       #
       # Test description.
    }

这将返回可接受的结果，但不像Get-ChildItem示例那样干净，因为没有内置的示例目的和示例输出的分离。

NAME
    Get-Example3

SYNOPSIS

    -------------------------- EXAMPLE 1 --------------------------

    PS > Get-Example

    Sample output

    Test description.

将行注解#替换为块注解<# ... #>并没有改变在.EXAMPLE之后添加文本会破坏语法的行为。
我在Microsoft的文档中没有看到如何设置示例主题的文档：

powershell

来源：https://stackoverflow.com/questions/75988603/set-topic-of-comment-based-help-example

1条答案

按热度按时间

hi3rlvi21#

关于使基于注解的帮助显示类似于二进制cmdlet的示例，即Get-ChildItem：

--- Example 1: Get child items from a file system directory ---

我不相信这是可能的comment based help，请注意，二进制cmdlet没有这样的事情，作为评论为基础的帮助，他们的帮助来自外部MAML文件。例如，如果您使用PowerShell 7+，则可以使用以下命令查看Get-ChildItem的外部帮助：

Get-Content (Get-Command Get-ChildItem).HelpFile

这些文件通常使用New-ExternalHelp从platyPS Module生成。
虽然，您可以在PowerShell模块中使用外部帮助文件，就像使用二进制cmdlet一样，但部分脚本模块中基于注解的帮助的语法解释了我们如何创建Markdown文档，然后使用New-ExternalHelp导出XML，最后，在我们的模块函数中，我们将其指向外部帮助：

# .ExternalHelp GetExampleModule-help.xml
function Get-Example {
    ...
    ...
}

至于如何表示函数的“控制台输出”，这里有几个例子，这可能没有文档记录，因为这取决于所有者的决定。

function Get-Example {
    <#
        .EXAMPLE
        Get-Example foo

        !! Sample output with
        !! foo

        Test description with foo

        .EXAMPLE
        Get-Example bar

        > Sample output with
        > bar

        Test description with bar

        .EXAMPLE
        Get-Example baz

        # Sample output with
        # baz

        Test description with baz
    #>
}

Get-Help Get-Example -Examples

PowerShell 7.4中此函数的帮助示例如下所示：

NAME
    Get-Example

SYNOPSIS

    -------------------------- EXAMPLE 1 --------------------------
    
    PS > Get-Example foo

    !! Sample output with
    !! foo

    Test description with foo



    -------------------------- EXAMPLE 2 --------------------------

    PS > Get-Example bar

    > Sample output with
    > bar

    Test description with bar



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

    PS > Get-Example baz

    # Sample output with
    # baz

    Test description with baz

赞(0）回复(0）举报 2023-05-22

我来回答

powershell 设置基于注解的帮助示例的主题

1条答案

相关问题

热门标签

最新问答