Version 2 of PowerShell introduced structured help in their work, without having to write MAML help files.

Why Not Write My Own Help Function?

One of the things I saw a good bit of in the Scripting Games this year was that people wrote their own help functions. 

The usual pattern included if the script was run with a particular switch or no switch, like My-Script.ps1 –help, a little help text would be spewed out.  I use that word (spewed) specifically, as the help text is often just printed to the console and does not work with Get-Help (and all the cool things I talked about with that yesterday..).  Even if the author went through the trouble of making the output of his help function look like a PowerShell help file, you still loose the capabilities to do things like

get-help my-command.ps1 –parameter identity

With just a **less** **work**, you could turn that help function into Comment Based Help.



I say **less work**, because instead of having to write a function and set a parameter and logic to call that help function, the you can just wrap the help in block comments and put a period in front of the keywords.



### What it Looks Like..
<# 
   .Synopsis 
    Do-Something makes the magic happen 
   .Example Get-ADUser | Do-Something
    Takes an ADUser and does something to that user.    
   .Parameter  Identity
    Takes an ADUser
   .Notes 
    NAME: Do-Something
    AUTHOR: [email protected]
    LASTEDIT: 04/27/2011 12:11:58 
    KEYWORDS: 
   .Link 
    Http://blog.usepowershell.com 
#> 
Or if you really like the hash symbol
#.Synopsis 
#Do-Something makes the magic happen 
#.Example Get-ADUser | Do-Something
#Takes an ADUser and does something to that user.    
#.Parameter  Identity
#Takes an ADUser
#.Notes 
#NAME: Do-Something
#AUTHOR: [email protected]
#LASTEDIT: 04/27/2011 12:11:58 
#KEYWORDS: 
#.Link 
#Http://blog.usepowershell.com 
### What Can You Add?




I won’t go into great detail on what the segments of help can be, as the Technet documentation does a great job, but I will highlight the different segments.
  • Synopsis
  • Description
  • Parameter (one for each parameter the function or script can take)
  • Example (as many as your heart desires or you need to show the different use cases for the function or script)
  • Inputs
  • Outputs (please use this if you export a custom object and describe what is contained in it)
  • Notes
  • Link (to online help or resources OR other related topics.  Can be used multiple times, once for each related resource)
  • Component
  • Role
  • Functionality
  • ForwardHelpTargetName (to redirect your help topic)
  • ForwardHelpCategory
  • RemoteHelpRunspace (used by Export-PSSession)
  • ExternalHelp

    Where Does It Go?

    Comment Based Help can be stored at the beginning of a function,

function Do-Something()
{
    <# 
       .Synopsis 
        Do-Something makes the magic happen 
       .Example Get-ADUser | Do-Something
        Takes an ADUser and does something to that user.    
       .Parameter  Identity
        Takes an ADUser
       .Notes 
        NAME: Do-Something
        AUTHOR: [email protected]
        LASTEDIT: 04/27/2011 12:11:58 
        KEYWORDS: 
       .Link 
        Http://blog.usepowershell.com 
    #>
    param (
        [Parameter(ValueFromPipeline=$true)
        [Microsoft.ActiveDirectory.Management.ADUser]
        $Identity)
    process
    {
        #Do Something of Value here
    }

}
at the end of a function,
function Do-Something()
{
    param (
        [Parameter(ValueFromPipeline=$true)
        [Microsoft.ActiveDirectory.Management.ADUser]
        $Identity)
    process
    {
        #Do Something of Value here
    }
    <# 
       .Synopsis 
        Do-Something makes the magic happen 
       .Example Get-ADUser | Do-Something
        Takes an ADUser and does something to that user.    
       .Parameter  Identity
        Takes an ADUser
       .Notes 
        NAME: Do-Something
        AUTHOR: [email protected]
        LASTEDIT: 04/27/2011 12:11:58 
        KEYWORDS: 
       .Link 
        Http://blog.usepowershell.com 
    #>
}
or before the function keyword.

<# 
   .Synopsis 
    Do-Something makes the magic happen 
   .Example Get-ADUser | Do-Something
    Takes an ADUser and does something to that user.
.Parameter Identity Takes an ADUser .Notes NAME: Do-Something AUTHOR: [email protected] LASTEDIT: 04/27/2011 12:11:58 KEYWORDS: .Link Http://blog.usepowershell.com

>

function Do-Something() { param ( [Parameter(ValueFromPipeline=$true) [Microsoft.ActiveDirectory.Management.ADUser] $Identity) process { #Do Something of Value here } }

NOTE: In a script, you can only use the before the body of the script or after the body of the script, since the script is self contained in one file.

 

And if you order right now..

And if that’s not easy enough, there are several functions that have been written to help you create your comment based help.

Want more great reading? Check out my reading list!