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!'

}