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.


TROUBLESHOOTING NOTE: 
	Default values and a value for "Accept Wildcard characters" do not appear in
	the parameter attribute table even when they are defined in the function or
	script. To help users, provide this information in the parameter description.


 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 Get-Function 
		{
			<#
			.< help keyword>
			< help content>
			#>

			<function commands>
	}


	-or -

		function Get-Function 
		{
			<function commands>

			<#
			.< help keyword>
			< help content>
			#>
	}

	-or -

		<#
		.< help keyword>
		< help content>
		#>
		function Get-Function { }



 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. However, if the script is signed, place
	 Comment-based Help at the beginning of the script file. The end of the
	 script file is occupied by the signature block. 



	For example:

		<#
		.< help keyword>
		< help content>
		#>


		function Get-Function { }

	-or-


		function Get-Function { }

		<#
		.< 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 detail to the syntax.
			If you do not specify a parameter type, the "Object" type is 
			inserted as the default value.

		Parameter List: 
			The Parameter list in the Help topic is generated from the function
			or script syntax and from the descriptions that you add by using the
			Parameters keyword. The function parameters appear in the "Parameters"
			section of the Help topic in the same order that they appear in
			the function or script syntax. The spelling and capitalization of
			parameter names is also taken from the syntax; it is not affected
			by the parameter name specified by the Parameter keyword. 

		Common Parameters: 
			The common parameters are added to the syntax and parameter list
			of the Help topic, even if they have no effect. For more information
			about the common parameters, see about_CommonParameters.

		Parameter Attribute Table: 
			Get-Help generates the table of parameter attributes that appears
			when you use the Full or Parameter parameter of Get-Help. The value
			of the Required, Position, and Default value attributes is taken
			from the function or script syntax.

			TROUBLESHOOTING NOTE: 
				Default values do not appear in the parameter attribute table, even
				when they are defined in the function or script. To help users, list
				the default value in the parameter description.

		Remarks: 
			The Remarks section of the Help topic is automatically generated
			from the function or script name. You cannot change or affect its
			content.


EXAMPLES

	Example 1: Comment-based Help for a Function

		The following sample function includes comment-based Help:

			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
			http://www.fabrikam.com/extension.html

			.LINK
			Set-Item
			#>
		}



		The results are as follows:

		C:\PS> get-help add-extension -full

		NAME
			Add-Extension

		SYNOPSIS
			Adds a file name extension to a supplied name.

		SYNTAX
			Add-Extension [[-Name] <String>] [[-Extension] <String>] [<CommonParameters>]

		DESCRIPTION
			Adds a file name extension to a supplied name. Takes any strings for the file name or extension.

		PARAMETERS
		 -Name
			 Specifies the file name.
	
			 Required?					false
			 Position?					0
			 Default value			
			 Accept pipeline input?	 false
			 Accept wildcard characters?  
	
		 -Extension
			 Specifies the extension. "Txt" is the default.
	
			 Required?					false
			 Position?					1
			 Default value			
			 Accept pipeline input?	 false
			 Accept wildcard characters?  
	
			<CommonParameters>
			 This cmdlet supports the common parameters: -Verbose, -Debug,
			 -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
			 -OutBuffer and -OutVariable. For more information, type
			 "get-help about_commonparameters".


		INPUTs
			None. You cannot pipe objects to Add-Extension.

		OUTPUTS
			System.String. Add-Extension returns a string with the extension or file name.
	
			-------------------------- EXAMPLE 1 --------------------------

			C:\PS> extension -name "File"
			File.txt

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

			C:\PS> extension -name "File" -extension "doc"
			File.doc

			-------------------------- EXAMPLE 3 --------------------------

			C:\PS> extension "File" "doc"
			File.doc

		RELATED LINKS
			http://www.fabrikam.com/extension.html
			Set-Item



	Example 2: Parameter Descriptions in Function Syntax

		This example is the same as the previous one, except that the parameter
		descriptions are inserted in the function syntax. This format is most
		useful when the descriptions are brief. 


		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.

			.DESCRIPTION
			Adds a file name extension to a supplied name. Takes any strings for the file name or extension.

			.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
			http://www.fabrikam.com/extension.html

			.LINK
			Set-Item
			#>
	}




	Example 3: Comment-based Help for a Script

		The following sample script includes comment-based Help. 

		Notice the blank lines between the closing "#>" and the Param statement. 
		In a script that does not have a Param statement, there must be at least
		two blank lines between the final comment in the Help topic and the first
		function declaration. Without these blank lines, Get-Help associates the
		Help topic with the function, not the script.

		 <#
		 .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 { }
		 ...


		The following command gets the script Help. Because the script is not
		in a directory that is listed in the Path environment variable, the
		Get-Help command that gets the script Help must specify the script path.


			PS C:\ps-test> get-help .\update-month.ps1 -full

			NAME
				C:\ps-test\Update-Month.ps1

			SYNOPSIS
				Performs monthly data updates.

			SYNTAX
				C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
				<String>] [<CommonParameters>]

			DESCRIPTION
				The Update-Month.ps1 script updates the registry with new data
				generated during the past month and generates a report.

			PARAMETERS
			 -InputPath
				 Specifies the path to the CSV-based input file.
	
				 Required?					true
				 Position?					0
				 Default value			
				 Accept pipeline input?	 false
				 Accept wildcard characters?  
	
			 -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.
	
				 Required?					false
				 Position?					1
				 Default value			
				 Accept pipeline input?	 false
				 Accept wildcard characters?  
	
			 <CommonParameters>
				 This cmdlet supports the common parameters: -Verbose, -Debug,
				 -ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
				 -OutBuffer and -OutVariable. For more information, type,
				 "get-help about_commonparameters".

			INPUTS
				 None. You cannot pipe objects to Update-Month.ps1.

			OUTPUTS
				 None. Update-Month.ps1 does not generate any output.


			-------------------------- EXAMPLE 1 --------------------------
	
			C:\PS> .\Update-Month.ps1

			-------------------------- EXAMPLE 2 --------------------------
	 
			C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

			-------------------------- EXAMPLE 3 --------------------------

			C:\PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath 
			C:\Reports\2009\January.csv
	
			RELATED LINKS



	Example 4:  Redirecting to an XML File

		You can write XML-based Help topics for functions and scripts. Although
		comment-based Help is easier to implement, XML-based Help is required
		if you want more precise control over Help content or if you are
		translating Help topics into multiple languages.  

		The following example shows the first few lines of the Update-Month.ps1
		script. The script uses the ExternalHelp keyword to specify the path to
		an XML-based Help topic for the script.


			#  .ExternalHelp C:\MyScripts\Update-Month-Help.xml


			param ([string]$InputPath, [string]$OutPutPath)

			function Get-Data { }
			...



	 The following example shows the use of the ExternalHelp keyword in a
	 function.


			function Add-Extension 
			{
				param ([string] $name, [string]$extension = "txt")
				$name = $name + "." + $extension
				$name

				# .ExternalHelp C:\ps-test\Add-Extension.xml
		}


	Example 5:  Redirecting to a Different Help Topic

		The following code is an excerpt from the beginning of the built-in
		Help function in Windows PowerShell, which displays one screen of Help
		text at a time. Because the Help topic for the Get-Help cmdlet describes
		the Help function, the Help function uses the ForwardHelpTargetName and
		ForwardHelpCategory keywords to redirect the user to the Get-Help cmdlet
		Help topic.

			function help 
			{

			<#
			.FORWARDHELPTARGETNAME Get-Help
			.FORWARDHELPCATEGORY Cmdlet
			#>
			[CmdletBinding(DefaultParameterSetName='AllUsersView')]
			param(
				[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
				[System.String]
				${Name},
				 ...


		The following command uses this feature:

			C:\PS> get-help help

			NAME
				Get-Help

			SYNOPSIS
				Displays information about Windows PowerShell cmdlets and concepts.
			...


SEE ALSO
	about_Functions
	about_Functions_Advanced_Parameters
	about_Scripts
	"How to Write Cmdlet Help" (http://go.microsoft.com/fwlink/?LinkID=123415)