{"id":285,"date":"2018-04-24T00:01:16","date_gmt":"2018-04-24T08:01:16","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/koryt\/?p=285"},"modified":"2020-04-29T10:26:07","modified_gmt":"2020-04-29T17:26:07","slug":"doing-more-with-functions-comment-based-help","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/scripting\/doing-more-with-functions-comment-based-help\/","title":{"rendered":"Doing More With Functions: Comment-Based Help"},"content":{"rendered":"

I just wanted to throw together a post highlighting how cool and easy it is to add help data to your own Functions and scripts.<\/p>\n

The help data gets added via comments. For functions the help data can go in three places:<\/p>\n

    \n
  1. Before the function keyword (I like it up here)<\/li>\n
  2. Between the open curly brace and the param() statement<\/li>\n
  3. At the bottom of the function before the closing curly brace (I hate this spot)<\/li>\n<\/ol>\n

    For scripts we just put it at the top of your script before you type the param() statement, or at the bottom, but the bottom will mess with code signing.<\/p>\n

    Syntax just involves using a dot before the help keyword and then typing the help you want for it on the next line:<\/p>\n

    <#\r\n.<keyword>\r\n<help data for it>\r\n#><\/pre>\n
    Here is a list of all the keywords<\/a> I found and short descriptions of them:<\/p>\n
    <#\r\n.SYNOPSIS\r\nA brief description of the function or script.\r\nThis keyword can be used only once in each topic.\r\n\r\n.DESCRIPTION\r\nA detailed description of the function or script.\r\nThis keyword can be used only once in each topic.\r\n\r\n.PARAMETER <Parameter-Name>\r\nThe description of a parameter.\r\nAdd a \".PARAMETER\" keyword for each parameter in the function or script syntax.\r\n\r\n.EXAMPLE\r\nA sample command that uses the function or script, optionally followed by sample output and a description.\r\nRepeat this keyword for each example.\r\n\r\n.INPUTS\r\nThe Microsoft .NET Framework types of objects that can be piped to the function or script.\r\nYou can also include a description of the input objects.\r\n\r\n.OUTPUTS\r\nThe .NET Framework type of the objects that the cmdlet returns.\r\nYou can also include a description of the returned objects.\r\n\r\n.NOTES\r\nAdditional information about the function or script.\r\n\r\n.LINK\r\nThe name of a related topic.\r\nThe value appears on the line below the \".LINK\" keyword and must be preceded by a comment symbol # or included in the comment block.\r\nRepeat the \".LINK\" keyword for each related topic.\r\n\r\nThe \"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\".\r\n\r\n.COMPONENT\r\nThe technology or feature that the function or script uses, or to which it is related.\r\n\r\n.ROLE\r\nThe user role for the help topic.\r\n\r\n.FUNCTIONALITY\r\nThe intended use of the function.\r\n\r\n.FORWARDHELPTARGETNAME <Command-Name>\r\nRedirects to the help topic for the specified command.\r\nYou can redirect users to any help topic, including help topics for a function, script, cmdlet, or provider.\r\n\r\n.FORWARDHELPCATEGORY <Category>\r\nSpecifies the help category of the item in \"ForwardHelpTargetName\".\r\nValid values are \"Alias\", \"Cmdlet\", \"HelpFile\", \"Function\", \"Provider\", \"General\", \"FAQ\", \"Glossary\", \"ScriptCommand\", \"ExternalScript\", \"Filter\", or \"All\".\r\nUse this keyword to avoid conflicts when there are commands with the same name.\r\n\r\n.REMOTEHELPRUNSPACE <PSSession-variable>\r\nSpecifies a session that contains the help topic.\r\nEnter a variable that contains a \"PSSession\".\r\n\r\n.EXTERNALHELP\r\nSpecifies an XML-based help file for the script or function.\r\n\r\n#>\r\n\r\n<\/pre>\n
    For the most part, I recommend using a few of the most common and important ones, which I think are:<\/p>\n