Documentation–documenting variables in a script/function

A few weeks ago, I gave a PowerShell course during which the issue of documentation came up. The point I made was documentation is a good thing – and the more the better. The delegates really liked the comment based help approach. But it often does not go quite far enough.

One additional thing you can do is to document individual variables. Each variable object lives in the Variable: drive. Variables are , like everything PowerShell, an object. When you get child items of a variable, the variable is returned of the type System.Management.Automation.PSVariable. There are some special PowerShell variables (QuestionMarkVariable, LocalVariable, SessionStateCapacityVariable, and NullVariable). All of these objects have a Description property which enables you to describe each variable.

So you could do this:

$I = ‘10.0.0.100’
(dir variable:I).description  = ‘the new IP address for the new server’
$iold = ‘10.0.1.200’
(dir variable:iold).description  = ‘the new IP address for the new server’
Dir Variable: | Format-Table name,description –a

I’ve not used this approach much, but I probably do so in the future for production scripts at least!