帮助文档是powershell这门脚本语言的一个很方便的特性，我们在脚本的代码里面注释的同时，这些注释又可以作为帮助文档使用，使用get-help命令可以把他们提取出来。
通常我们可以执行这样的命令get-help ls -detailed，来获取一个命令详细的帮助信息。
01.注释语法
有两种
行注释
# .< help keyword>
# <help content>
-or -
块注释
<#
.< help keyword>
< help content>
#>
help keyword 指的是，是一些特定的关键词，举个例子 ,.Description关键词
<#
.Description
The Get-Function function displays the name and syntax of all functions in the session.
#>
02.关键词
.SYNOPSIS（大纲）
关于脚本或者函数的简短介绍
.DESCRIPTION
关于函数或者脚本的详细介绍
.PARAMETER <Parameter-Name>
关于参数的解释
.EXAMPLE
脚本或者函数的使用例子
.INPUTS
.net类型的对象可以使用管道传给函数，关于输入对象的描述
.OUTPUTS
cmdlet能输出.net类型的对象，关于输出对象的描述
.NOTES
关于函数或者脚本的额外信息
.LINK
相关链接，在使用 get-help online选项的时候会打开对应的网址
.COMPONENT
函数或者脚本使用的组件
.Role
职能， get－help过滤搜索结果的时候用得到
.FORWARDHELPTARGETNAME <Command-Name>
重定向到其他帮助主题
.FORWARDHELPCATEGORY <Category>
指定项目的帮助类别，使用这个关键词避免同名时的冲突
以下是有效值：
- Alias
- Cmdlet
- HelpFile
- Function
- Provider
- General
- FAQ
- Glossary
- ScriptCommand
- ExternalScript
- Filter
- All
.EXTERNALHELP <XML Help File>
使用外部xml帮助文件
03.函数中的帮助文档
001.帮助文档放在函数开头
function MyProcess
{
<#
.Description
The MyProcess function gets the Windows PowerShell process.
#>
Get-Process powershell
}
002.帮助文档放在函数体末尾
function MyFunction
{
Get-Process powershell
<#
.Description
The MyProcess function gets the Windows PowerShell process.
#>
}
003.帮助文档放在函数前面
<#
.Description
The MyProcess function gets the Windows PowerShell process.
#>
function MyFunction { Get-Process powershell}
04.脚本中的帮助文档
同函数，可以放在开头和结尾位置
05.示例
001.函数帮助文档
function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
.DESCRIPTION
Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.
.PARAMETER Name
Specifies the file name.
.PARAMETER Extension
Specifies the extension. "Txt" is the default.
.INPUTS
None. You cannot pipe objects to Add-Extension.
.OUTPUTS
System.String. Add-Extension returns a string with the extension or file name.
.EXAMPLE
C:\PS> extension -name "File"
File.txt
.EXAMPLE
C:\PS> extension -name "File" -extension "doc"
File.doc
.EXAMPLE
C:\PS> extension "File" "doc"
File.doc
.LINK
Online version: http://www.fabrikam.com/extension.html
.LINK
Set-Item
#>
}
002.脚本帮助文档
<#
.SYNOPSIS
Performs monthly data updates.
.DESCRIPTION
The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.
.PARAMETER InputPath
Specifies the path to the CSV-based input file.
.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.
.INPUTS
None. You cannot pipe objects to Update-Month.ps1.
.OUTPUTS
None. Update-Month.ps1 does not generate any output.
.EXAMPLE
C:\PS> .\Update-Month.ps1
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv
.EXAMPLE
C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath C:\Reports\2009\January.csv
#>
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
003.param 参数的说明
function Add-Extension
{
param
(
[string]
# Specifies the file name.
$name,
[string]
# Specifies the file name extension. "Txt" is the default.
$extension = "txt"
)
$name = $name + "." + $extension
$name
<#
.SYNOPSIS
Adds a file name extension to a supplied name.
...
#>
004.重定向到xml文件
# .ExternalHelp C:\MyScripts\Update-Month-Help.xml
param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
005.重定向到其他帮助主题
function help
{
<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
[CmdletBinding(DefaultParameterSetName='AllUsersView')]
param(
[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
[System.String]
${Name},
...
网友评论