PowerTip of the Day-Add Help to Your Functions

原文地址：http://app.en25.com/e/es.aspx?s=1403&e=5382&elq=d8bc53b04e51496c9e3ef39e28976a68

原文：

You should simply copy and paste the following block comment right above your functions and magically Get-Help works with your functions, too!

<#
     .SYNOPSIS
          A brief description of the function.
     .DESCRIPTION
          A detailed description of the function.
     .PARAMETER  something
          The description of the first parameter.
     .EXAMPLE
          PS C:\> My-Test -something 'string value'
     .NOTES
          Additional information about the function goes here.
     .LINK
          about_functions_advanced
#>

Function My-Test($something) { 'Call Get-Help My-Test to see my help!' }

So to get Help, after running the code, you should try this:

Get-Help My-Test

Get-Help My-Test -examples

You won't get help with PowerShell v1, and you won't get Help if the Help block is wrongly located. It can be right above a function (no more than one blank line), or first/last thing inside the function.

 

 

翻译：

拷贝如下代码放到你的函数之前，这样通过Get-Help就可以查看函数的帮助信息。

<#
     .SYNOPSIS
          A brief description of the function.
     .DESCRIPTION
          A detailed description of the function.
     .PARAMETER  something
          The description of the first parameter.
     .EXAMPLE
          PS C:\> My-Test -something 'string value'
     .NOTES
          Additional information about the function goes here.
     .LINK
          about_functions_advanced
#>

Function My-Test($something) { 'Call Get-Help My-Test to see my help!' }
需要获取函数的帮助功能，在运行如上代码之后，尝试下面的代码：

Get-Help My-Test

Get-Help My-Test -examples

在PowerShell版本1中是无法获取帮助的，并且如果帮助代码块放错位置的话也是无法获取帮助信息的。它应该就放在函数体的上面（空行不要多于一行），或者是函数体的最前面或者最后面。

 

笔记：

类似在c#中方法名前敲三个斜线。

最后一句很绕，意思是说，可以这样声明：

Function My-Test($something) {

'Call Get-Help My-Test to see my help!'

<#

     .SYNOPSIS

          A brief description of the function.

     .DESCRIPTION

          A detailed description of the function.

     .PARAMETER something

          The description of the first parameter.

     .EXAMPLE

          PS C:\> My-Test -something 'string value'

     .NOTES

          Additional information about the function goes here.

     .LINK

          about_functions_advanced

#>

}

也可以这样声明：

Function My-Test($something) {

<#

     .SYNOPSIS

          A brief description of the function.

     .DESCRIPTION

          A detailed description of the function.

     .PARAMETER something

          The description of the first parameter.

     .EXAMPLE

          PS C:\> My-Test -something 'string value'

     .NOTES

          Additional information about the function goes here.

     .LINK

          about_functions_advanced

#>

'Call Get-Help My-Test to see my help!'

}

但是不能这样声明：

Function My-Test($something) {

'Call Get-Help My-Test to see my help!'

<#

     .SYNOPSIS

          A brief description of the function.

     .DESCRIPTION

          A detailed description of the function.

     .PARAMETER something

          The description of the first parameter.

     .EXAMPLE

          PS C:\> My-Test -something 'string value'

     .NOTES

          Additional information about the function goes here.

     .LINK

          about_functions_advanced

#>

'Call Get-Help My-Test to see my help!'

}