Placing Comment-Based Help

What an amazing event. I'm now reading through each of the Advanced entries in a vain attempt to whittle the entries down to a short list. It's an incredibly difficult task, which is testament to your skill and diligence. We are so lucky to have so many competent scripters in the community.

As I read through the comments on each script, I've noticed several that say:

"Help should be nested under the function to work properly."

Au contraire! This is not true and I want to make sure that people who see this comment are not misled. The Windows PowerShell team designed comment-based help to be really flexible.

As I explained in about_Comment_Based_Help, you can put comment-based help for a function in one of three positions:

  • At the beginning of the function body
  • At the end of the function body
  • On the line before the Function keyword

So, all of these work.

function Move-OldFiles
{
<#
.Synopsis         
 Moves old log files to an archive directory.          
#>
      Param
      (
         [parameter(Mandatory=$true)]
         [String]
         $InputDirectory
      )
}
function Move-OldFiles
{
  Param
      (
         [parameter(Mandatory=$true)]
         [String]
         $InputDirectory
      )
   #Script logic goes here

<#
.Synopsis         
 Moves old log files to an archive directory.          
#>
}
<#
.Synopsis         
 Moves old log files to an archive directory.          
#>
function Move-OldFiles
{
  Param
      (
         [parameter(Mandatory=$true)]
         [String]
         $InputDirectory
      )
   #Script logic goes here
}

If you place the comment-based help on the line before the Function keyword, make sure that there is, at most, one blank line between the end of the comment-based help and the line with the function keyword. To avoid this problem, I always make sure that there are no blank lines between the end of the comment-based help and the Function keyword.

When reading the comments about your solutions, please remember that we are all volunteers. Everyone who takes the time to comment on your solution is trying to help, and should be appreciated, but not every comment is correct. Trust, but verify!

About the Author

June Blender

June Blender was a senior programming writer on the Windows PowerShell team at Microsoft from Windows PowerShell 1.0 – 3.0. You see her work every time you type Get-Help for the core modules. She’s now working on the Windows Azure Active Directory SDK team, and she remains an avid Windows PowerShell user and a passionate user advocate. She’s a guest blogger for the Scripting Guys and she tweets Windows PowerShell tips on Twitter at @juneb_get_help.

A 16-year veteran of Microsoft, June lives in magnificent Escalante, Utah, where she works remotely when she’s not out hiking, canyoneering, taking Coursera classes, or convincing lost tourists to try Windows PowerShell. She believes that outstanding documentation is a collaborative effort, and she welcomes your comments and contributions to Windows PowerShell and Windows Azure Help.

4 Comments

  1. Thanks for this post.

    Please can you clarify whether it's acceptable to have the help at the start of the script, in one block (followed by two line breaks). I received a comment that my help was in the wrong place and would not bind to the function. about_comment_based_help says this is an acceptable place for comment-based help in scripts but the comment I received makes me wonder if I misused it.

  2. Hi, Matt.

    Yes, it’s definitely acceptable to have the help at the start of the script (first line) in one block followed by two blank lines. In fact, that's the typical placement for script help.

    In a script, the comment-based help must be the first item, or it must be preceded only by comments or blank lines. And, there must be two blank lines between the end of the comment-based help and the first function; otherwise Get-Help interprets the help to be function help, not script help.

    But test it for yourself. Pop your script in a file, save it, and run Get-Help .ps1

    For reference: about_comment_based_help:
    http://technet.microsoft.com/en-us/library/hh847834.aspx