如何定义自定义命令的文档（使用 Get-Command 或 Get-Help）

Question

假设我有一个自定义命令：

function Search-ForStringInFile($string)
{
        ls -Recurse | Select-String -Pattern "$string" -List | Select Path
}

并且我希望能够运行 Get-Help Search-ForStringInFile 或 Get-Command Search-ForStringInFile 来获得命令的描述。

Description: Searches for keyword in all files in / under current directory

我可以在 function 上使用特殊注释语法来添加此文档吗？

Answer 1

这称为基于评论的帮助。实际上，PowerShell ISE 有一个非常棒的代码片段，可以准确地执行您想要执行的操作。只需按 Control+J 并选择 'Cmdlet - Advanced Function' 即可加载我将在下面提供的片段：

<#
.Synopsis
   Short description
.DESCRIPTION
   Long description
.EXAMPLE
   Example of how to use this cmdlet
.EXAMPLE
   Another example of how to use this cmdlet
#>
function Verb-Noun
{
}

为以上各项填写值后（see the docs here 用于所有可用字段）并按 F5，帮助将出现在您的函数中。

PS>Get-Help Verb-Noun
NAME
    Verb-Noun

SYNOPSIS
    Short description


SYNTAX
    Verb-Noun [-Param1] <Object> [-Param2 <Int32>] [-WhatIf] [-Confirm] [<CommonParameters>]

    Verb-Noun [-Param3 <String>] [-WhatIf] [-Confirm] [<CommonParameters>]


DESCRIPTION
    Long description


PARAMETERS
    -Param1 <Object>
        Param1 help description

        Required?                    true
        Position?                    1
        Default value                
        Accept pipeline input?       true (ByValue, ByPropertyName)
        Accept wildcard characters?  false

    -Param2 <Int32>
        Param2 help description

        Required?                    false
        Position?                    named
        Default value                0
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -Param3 <String>
        Param3 help description

        Required?                    false
        Position?                    named
        Default value                
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -WhatIf [<SwitchParameter>]

        Required?                    false
        Position?                    named
        Default value                
        Accept pipeline input?       false
        Accept wildcard characters?  false

    -Confirm [<SwitchParameter>]

        Required?                    false
        Position?                    named
        Default value                
        Accept pipeline input?       false
        Accept wildcard characters?  false

    <CommonParameters>
        This cmdlet supports the common parameters: Verbose, Debug,
        ErrorAction, ErrorVariable, WarningAction, WarningVariable,
        OutBuffer, PipelineVariable, and OutVariable. For more information, see 
        about_CommonParameters (https:/go.microsoft.com/fwlink/?LinkID=113216). 

INPUTS
    Inputs to this cmdlet (if any)


OUTPUTS
    Output from this cmdlet (if any)


NOTES


        General notes

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

    PS C:\>Example of how to use this cmdlet






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

    PS C:\>Another example of how to use this cmdlet







RELATED LINKS

因此，要为您自己的 cmdlet 添加帮助，您只需在函数中添加相同的注释块。您可以将它放在三个位置之一：

函数声明之前
函数声明后(ewww)
在你的函数结束时（不是要发表意见，但选择这个选项在道德上是错误的）。

文档还给出了每个 the approved locations here 的示例。

如何定义自定义命令的文档（使用 Get-Command 或 Get-Help）

How to define documentation on custom command (using Get-Command or Get-Help)

powershell

documentation-generation

powershell-5.0

powershell-v5.1