{"id":144,"date":"2011-03-15T14:33:06","date_gmt":"2011-03-15T20:33:06","guid":{"rendered":"http:\/\/ryan.witschger.net\/?p=144"},"modified":"2011-03-15T14:33:06","modified_gmt":"2011-03-15T20:33:06","slug":"adding-help-to-a-powershell-script","status":"publish","type":"post","link":"http:\/\/www.Get-Blog.com\/?p=144","title":{"rendered":"Adding Help to a PowerShell Script"},"content":{"rendered":"

With the scripting games coming up, I noticed that they will be adding stars to your work based on the addition of script help blocks that are compatible with the PowerShell “Comment Based Help”. Basically, this is a form of writing a comment block that works in conjunction with the get-help cmdlet that is included with PowerShell.<\/p>\n

With this post I am hoping spread the information that this is possible just as much as the how to do it. I think that most script writers don’t even know it’s possible, and I’ll be honest that while I’ve know that you can do it, I don’t include in all of my own scripts.<\/p>\n

So, you can add comment based help either to a script or to a function. It is my opinion that you do not need to add the help to a function within a script as no one will be able to run a get-help against it; however, using the format provided to label your functions is probably a good idea.<\/p>\n

So, there are two ways to make a comment block and three places to put them. <\/p>\n

You can start all the lines in a block with # or you can surround all the lines with <# ...comments... #>. Either form is fine, but the later might be easier for large block; however, the former might be easier to follow if browsing the code. I typically like to start my lines with # as I can quickly see where all the comments start and stop.<\/p>\n

As far as where to place them, you can put them at the start of a function or script, at the end of a function or script,or just before the start of a function. Line breaks become very important as spaces between comments and their attached objects will detach them.<\/p>\n

Now the comments need to follow the format:<\/p>\n

# .KEYWORD<\/span>
\n#  Content<\/span>
\n#<\/span>
\n# .SYNOPSIS<\/span>
\n# This is an example of comment based help.<\/span><\/div><\/div>\n

So what kind of keywords are there? This is taken from the help file:<\/p>\n

    .SYNOPSIS
\n        A brief description of the function<\/span> or script. This keyword can be used
\n        only once in<\/span> each topic.
\n
\n    .DESCRIPTION
\n        A detailed description of the function<\/span> or script. This keyword can be
\n        used only once in<\/span> each topic.
\n
\n    .PARAMETER  <<\/span>Parameter-<\/span>Name><\/span>
\n        The description of a parameter. You can include a Parameter keyword for<\/span>
\n        each parameter in<\/span> the function<\/span> or script syntax.
\n
\n        The Parameter keywords can appear in<\/span> any order in<\/span> the comment block,<\/span>but
\n        the function<\/span> or script syntax determines the order in<\/span> which the parameters
\n        (<\/span>and their descriptions)<\/span> appear in<\/span> Help topic. To change the order,<\/span>
\n        change the syntax.
\n 
\n        You can also specify a parameter description by placing a comment in<\/span> the
\n        function<\/span> or script syntax immediately before the parameter variable name.
\n        If<\/span> you use both a syntax comment and a Parameter keyword,<\/span> the description
\n        associated with the Parameter keyword is used,<\/span> and the syntax comment is
\n        ignored.
\n
\n    .EXAMPLE
\n        A sample command that uses the function<\/span> or script,<\/span> optionally followed
\n        by sample output and a description. Repeat this keyword for<\/span> each example.
\n
\n    .INPUTS
\n        The Microsoft .NET Framework types of objects that can be piped to the
\n        function<\/span> or script. You can also include a description of the input
\n        objects.
\n
\n    .OUTPUTS
\n        The .NET Framework type<\/span> of the objects that the cmdlet returns. You can
\n        also include a description of the returned objects.
\n
\n    .NOTES
\n        Additional information about the function<\/span> or script.
\n
\n    .LINK
\n        The name of a related topic. Repeat this keyword for<\/span> each related topic.
\n
\n        This content appears in<\/span> the Related Links section of the Help topic.
\n
\n        The Link keyword content can also include a Uniform Resource Identifier
\n        (<\/span>URI)<\/span> to an online version of the same Help topic. The online version
\n        opens when you use the Online parameter of Get-Help<\/span>. The URI must begin
\n        with "http"<\/span> or "https"<\/span>.<\/div><\/div>\n

There are even more past that, but I think that covers the main group. If you want to see them all and get more detailed information go to PowerShell and run Get-Help<\/span> about_Comment_Based_Help<\/span><\/code>.<\/p>\n

As well, there are several built in sections that are generated automatically: Name, Syntax, Parameter List, Common Parameters, Parameter Attribute Table, Remarks.<\/p>\n

To get more information and some good examples go to PowerShell and run Get-Help<\/span> about_Comment_Based_Help<\/span><\/code>.<\/p>\n","protected":false},"excerpt":{"rendered":"

With the scripting games coming up, I noticed that they will be adding stars to your work based on the addition of script help blocks that are compatible with the PowerShell “Comment Based Help”. Basically, this is a form of writing a comment block that works in conjunction with the get-help cmdlet that is included with PowerShell.<\/p>\n","protected":false},"author":1,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_mi_skip_tracking":false,"_monsterinsights_sitenote_active":false,"_monsterinsights_sitenote_note":"","_monsterinsights_sitenote_category":0,"footnotes":""},"categories":[4],"tags":[],"_links":{"self":[{"href":"http:\/\/www.Get-Blog.com\/index.php?rest_route=\/wp\/v2\/posts\/144"}],"collection":[{"href":"http:\/\/www.Get-Blog.com\/index.php?rest_route=\/wp\/v2\/posts"}],"about":[{"href":"http:\/\/www.Get-Blog.com\/index.php?rest_route=\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"http:\/\/www.Get-Blog.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/www.Get-Blog.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=144"}],"version-history":[{"count":0,"href":"http:\/\/www.Get-Blog.com\/index.php?rest_route=\/wp\/v2\/posts\/144\/revisions"}],"wp:attachment":[{"href":"http:\/\/www.Get-Blog.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=144"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"http:\/\/www.Get-Blog.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcategories&post=144"},{"taxonomy":"post_tag","embeddable":true,"href":"http:\/\/www.Get-Blog.com\/index.php?rest_route=%2Fwp%2Fv2%2Ftags&post=144"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}