Making Comment-Based Help Compatible

Share |

Join PowerShell.com!
Subscribe to Feed

PowerShell eBook
Sign up for
Your PowerTip of the Day:

Award-winning PowerShellPlus


Admin Guide to PowerShell Remoting


Mastering PowerShell eBook

In a previous tip, you learned how to add Comment-Based Help information to your own functions so that Get-Help can auto-document the usage. However, once you do this your functions break on PowerShell v.1 because v.1 does not know the block comment feature.

So to get the best of both worlds, you should add Comment-Based Help to all of your functions. However, do not use block comments, but rather regular line comments instead. This way, your functions work on v.1 and can provide a great Help experience on v.2:

function Test-Me($parameter) {
#.SYNOPSIS
# A useless function
#.DESCRIPTION
# This function really does nothing
#.NOTES
# Demonstrates comment based help
#.LINK
# http://www.powershell.com
#.EXAMPLE
# Test-Me "Hello World"
}

As you will see, on v.2 your function will still work with Get-Help and is not required to use the new block comments. You should just make sure you ran your function at least once to define it:

Get-Help Test-Me

Twitter This Tip! ReTweet this Tip!


Posted Nov 09 2009, 08:00 AM by ps1
Copyright 2012 PowerShell.com. All rights reserved.