Chapter 9. Writing help

 

You’ll notice in this book that each progressive chapter (through at least chapter 14) will make your tools progressively better and better. You could just take what you’ve learned to this point and stop, knowing that you have a functional, useful, and well-designed tool. But why stop now when it’s just getting fun?

We’re going to start focusing more and more on making your tools look, feel, smell, and taste (imagine that) more and more like a “real” PowerShell cmdlet. One way to do that is to have your tools include help that looks just like the help for PowerShell’s native cmdlets.

9.1. Comment-based help

Right now, if we try to ask the help system for assistance with our Get-SystemInfo function, we’ll get something like this:

NAME
    Get-SystemInfo

SYNTAX
    Get-SystemInfo [-ComputerName] <string[]> [[-ErrorLog] <string>]
    [-LogErrors]
    [<CommonParameters>]

ALIASES
    None

REMARKS
    Get-Help cannot find the Help files for this cmdlet on this computer.
    It is
    displaying only partial help.
        -- To download and install Help files for the module that includes
         this
    cmdlet, use Update-Help.

Not so helpful, really. In fact, it’s downright wrong, because despite what it says, running Update-Help won’t do anything to give our function better-looking, more-complete help. Fortunately, there’s an easy fix, shown in the following listing.

9.2. XML-based help

 
 
 

9.3. Coming up next

 
 
 
 

9.4. Labs

 
 
 
sitemap

Unable to load book!

The book could not be loaded.

(try again in a couple of minutes)

manning.com homepage
test yourself with a liveTest