TOPIC about_Comment_Based_Help SHORT DESCRIPTION Describes how to write comment-based Help topics for functions and scripts. LONG DESCRIPTION You can write comment-based Help topics for functions and scripts by using special Help comment keywords. The Get-Help cmdlet displays comment-based Help in the same format in which it displays the cmdlet Help topics that are generated from XML files. Users can use all of the parameters of Get-Help, such as Detailed, Full, Example, and Online, to display function and script Help. You can also write XML-based Help files for scripts and functions by using Help comment keywords, and you can redirect users to a different Help file. This topic explains how to write Help topics for functions and scripts. For information about how to display Help topics for functions and scripts, see Get-Help. SYNTAX FOR COMMENT-BASED HELP The syntax for comment-based Help is as follows: # .< help keyword> # <help content> -or - <# .< help keyword> < help content> #> Comment-based Help is written as a series of comments. You can type a comment symbol (#) before each line of comments, or you can use the "<#" and "#>" symbols to create a comment block. All the lines within the comment block are interpreted as comments. All of the lines in a comment-based Help topic must be contiguous. If a comment-based Help topic follows a comment that is not part of the Help topic, there must be at least one blank line between the last non-Help comment line and the beginning of the comment-based Help. Keywords define each section of comment-based Help. Each comment-based Help keyword is preceded by a dot (.). The keywords can appear in any order. The keyword names are not case-sensitive. For example, the Description keyword precedes a description of a function or script. <# .Description Get-Function displays the name and syntax of all functions in the session. #> The comment block must contain at least one keyword. Some of the keywords, such as EXAMPLE, can appear many times in the same comment block. The Help content for each keyword begins on the line after the keyword and can span multiple lines. SYNTAX FOR COMMENT-BASED HELP IN FUNCTIONS Comment-based Help for a function can appear in one of three locations: -- At the beginning of the function body. -- At the end of the function body. -- Before the Function keyword. There cannot be more than one blank line between the last line of the function Help and the Function keyword. For example: function MyFunction { <# .< help keyword> < help content> #> <function commands> } -or - function MyFunction { <function commands> <# .< help keyword> < help content> #> } -or - <# .< help keyword> < help content> #> function MyFunction { } SYNTAX FOR COMMENT-BASED HELP IN SCRIPTS Comment-based Help for a script can appear in one of the following two locations in the script. -- At the beginning of the script file. Script Help can be preceded in the script only by comments and blank lines. -- If the first item in the script body (after the Help) is a function declaration, there must be at least two blank lines between the end of the script Help and the function declaration. Otherwise, the Help is interpreted as being Help for the function, not Help for the script. -- At the end of the script file. For example: <# .< help keyword> < help content> #> function MyFunction { } -or- function MyFunction { } <# .< help keyword> < help content> #> COMMENT-BASED HELP KEYWORDS The following are valid comment-based Help keywords. They are listed in the order in which they typically appear in a Help topic along with their intended use. These keywords can appear in any order in the comment-based Help, and they are not case-sensitive. .SYNOPSIS A brief description of the function or script. This keyword can be used only once in each topic. .DESCRIPTION A detailed description of the function or script. This keyword can be used only once in each topic. .PARAMETER <Parameter-Name> The description of a parameter. You can include a Parameter keyword for each parameter in the function or script syntax. The Parameter keywords can appear in any order in the comment block, but the function or script syntax determines the order in which the parameters (and their descriptions) appear in Help topic. To change the order, change the syntax. You can also specify a parameter description by placing a comment in the function or script syntax immediately before the parameter variable name. If you use both a syntax comment and a Parameter keyword, the description associated with the Parameter keyword is used, and the syntax comment is ignored. .EXAMPLE A sample command that uses the function or script, optionally followed by sample output and a description. Repeat this keyword for each example. .INPUTS The Microsoft .NET Framework types of objects that can be piped to the function or script. You can also include a description of the input objects. .OUTPUTS The .NET Framework type of the objects that the cmdlet returns. You can also include a description of the returned objects. .NOTES Additional information about the function or script. .LINK The name of a related topic. Repeat this keyword for each related topic. This content appears in the Related Links section of the Help topic. The Link keyword content can also include a Uniform Resource Identifier (URI) to an online version of the same Help topic. The online version opens when you use the Online parameter of Get-Help. The URI must begin with "http" or "https". .COMPONENT The technology or feature that the function or script uses, or to which it is related. This content appears when the Get-Help command includes the Component parameter of Get-Help. .ROLE The user role for the Help topic. This content appears when the Get-Help command includes the Role parameter of Get-Help. .FUNCTIONALITY The intended use of the function. This content appears when the Get-Help command includes the Functionality parameter of Get-Help. .FORWARDHELPTARGETNAME <Command-Name> Redirects to the Help topic for the specified command. You can redirect users to any Help topic, including Help topics for a function, script, cmdlet, or provider. .FORWARDHELPCATEGORY <Category> Specifies the Help category of the item in ForwardHelpTargetName. Valid values are Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filter, or All. Use this keyword to avoid conflicts when there are commands with the same name. .REMOTEHELPRUNSPACE <PSSession-variable> Specifies a session that contains the Help topic. Enter a variable that contains a PSSession. This keyword is used by the Export-PSSession cmdlet to find the Help topics for the exported commands. .EXTERNALHELP <XML Help File Path> Specifies the path to an XML-based Help file for the script or function. In Windows Vista and later versions of Windows, if the specified path to the XML file contains UI-culture-specific subdirectories, Get-Help searches the subdirectories recursively for an XML file with the name of the script or function in accordance with the language fallback standards established for Windows Vista, just as it does for all XML-based Help topics. For more information about the cmdlet Help XML-based Help file format, see "How to Create Cmdlet Help" in the MSDN (Microsoft Developer Network) library at http://go.microsoft.com/fwlink/?LinkID=123415. AUTOGENERATED CONTENT The name, syntax, parameter list, parameter attribute table, common parameters, and remarks are automatically generated by the Get-Help cmdlet. Name: The Name section of a function Help topic is taken from the function name in the function syntax. The Name of a script Help topic is taken from the script file name. To change the name or its capitalization, change the function syntax or the script file name. Syntax: The Syntax section of the Help topic is generated from the function or script syntax. To add detail to the Help topic syntax, such as the .NET Framework type of a parameter, add the deta...
magdula294