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..

Or if you really like the hash symbol

### 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,

at the end of a function,

or before the function keyword.