The name of the cmdlet; think of this as the title of the help page.

Source:

Noun–Verb, where Noun and Verb are the arguments to the Cmdlet attribute attached to the cmdlet, highlighted here:

Example:

A brief summary of the cmdlet, typically just a single sentence.

Source:

The synopsis paragraph in the summary attached to the cmdlet.

Example:

This auto-generated section lays out all the possible parameters and parameter combinations that are valid for the cmdlet, using a common variant of the well-known Backus-Naur Form notation.

Source:

Derived from the parameters of your cmdlet.

This is where you explain-in as much detail as appropriate-what your cmdlet does, how to use it, what to watch out for, and things to keep in mind when using it. In other words, everything your user needs to know to use your cmdlet effectively, except for the details you add to specific parameters and to specific examples.

Source:

The description paragraphs in the summary attached to the cmdlet.

Example:

This section enumerates each of your parameters, documenting values for common properties (whether the parameter is required, what its default value is, etc.) and providing a description of each parameter, supplementing your cmdlet’s description.

Source:

The description paragraphs in the summary attached to a parameter, along with its Parameter and Alias attributes.

Example:

This auto-generated section enumerates each type of object that may be piped to your cmdlet.

Source:

The description paragraph and parameter type for each parameter decorated with the ValueFromPipeline or ValueFromPipelineByPropertyName argument in its Parameter attribute.

Example:

This auto-generated section enumerates each type of object that your cmdlet may return.

Source:

The argument to the OutputType attribute(s) attached to the cmdlet and the description paragraph of the referenced type.

Example:

Here you provide any ancillary information that may be relevant, just not worth cluttering up the main description with. Think of this as akin to footnotes.

Source:

A list of type alertSet in the doc-comments attached to the cmdlet. Each <item> constitutes one note. Within each <item>, the <term> is the title and the <description> is the content of the note. The <description> may be text only or it may contain one or more <para> elements.

Example:

Known Issues:

PowerShell does not layout multiple notes very well. To simulate multiple notes, it is better to use a single note (<item> element) with multiple paragraphs (<para> elements) and with no title (<term> element). (See source issue on GitHub: Multiple notes do not render as expected)

An important section but often given short shrift, this is where you show the world how to really use your cmdlet. You should include exactly what needs to be typed, describe what happens with the particular set of parameters you are using, and even show some sample output, when appropriate.

Source:

One or more <example> elements in the doc-comments attached to the cmdlet. Each example may contains one or more paragraphs (<para> elements preceding <code>) as introductory text, then the example invocation (<code> element), and one or more remarks (<para> elements following <code>).

Example:

Known Issues:

In principle, you can include introductory text as shown in the example; but in practice PowerShell does not render it particularly well. And in fact, when Chris investigated this reported issue, he noted that there were virtually no standard .NET cmdlets that even tried to include introductory paragraphs. It is better to describe your example in remarks following the <code> element. (See source issue on GitHub: No newline after an example’s introduction)

A list of related topics, typically other cmdlet names (e.g. Get-ChildItem, New-Alias, etc.), other PowerShell help topic names (e.g. about_Providers), or ordinary URLs pointing to web pages.

Source:

Paragraphs of type link, which may optionally include a uri attribute for web pages. Convention is not to include a uri for standard PowerShell help topics, since those would be immediately accessible with another invocation of Get-Help.

Example:

Known Issues:

If you include a URI in your link, PowerShell renders it by simply juxtaposing it next to the text, so the output would appear as:

Call me particular, but that is not user-friendly! I urge you to include some textual demarcation in your uri attribute. I recommend using the standard markdown format for hyperlinks:

The link will then be rendered by Get-Help like this (and could potentially be made into a live link should you pass the help text through a post-processor that understands markdown):

Of course, this could easily be compensated for by XmlDoc2CmdletDoc so perhaps by the time you read this it may already be fixed-see issue #10: Render related web links to be more user friendly.

Parameters

So far, you learned the fundamentals of documenting your PowerShell binary cmdlets written in C#. I’ve explained the basics of what was needed: adding a synopsis paragraph and description paragraphs to each cmdlet class, and also adding description paragraphs to each parameter. I then described all the moving pieces needed to be able to thoroughly document your custom set of PowerShell cmdlets.

This section provides a further bit of sanding and polishing, if you will, to really make your documentation shine! Specifically you will learn the particulars about documenting the parameters of your cmdlets.

Parameter Description

The parameter description is text of arbitrary length describing a given parameter. Consider the Flavor parameter, repeated here:

With no help file (i.e. without using XmlDoc2CmdletDoc), this description stems from the HelpMessage property:

However, with a help file present, the description instead comes from the description paragraph within the <summary> element immediately preceding the parameter. Since the goal here is to generate just such a help file, you should utilize this <summary> element for your description.

The HelpMessage property is still useful, though. When a parameter is required but not supplied on the command-line, PowerShell prompts you to enter its value. If you are not sure what it expects for the value, you can ask for more information at that prompt. That’s where the HelpMessage appears:

Parameter Enumerated Types

When my colleagues and I at NextIT were working to rapidly integrate XmlDoc2CmdletDoc into our build process, I noticed that we had to manually document the possible values for an enum. And, if you look at standard .NET cmdlets that is how they do it as well-this is clearly manually written documentation:

I thought we could do better, and so I tweaked XmlDoc2CmdletDoc to auto-document the enumerated values. Thus, with just this code:

You would get this output – notice the Possible values line automatically inserted:

(Of course, if you need or want to explain those enum values, you will still need manually written comments, but in many cases the auto-generated text would be sufficient.)

But there’s more. Notice at the very beginning-before using XmlDoc2CmdletDoc-the Syntax section listed the possible enum values right there:

But standard .NET cmdlets do not do this!

And that’s also the way that XmlDoc2CmdletDoc worked when I found it. But I really liked the idea of listing the enum values in the Syntax section so I updated the code to do that. (Thus you will find support for both forms of auto-documenting enums merged into the latest version of XmlDoc2CmdletDoc!)

Parameter Alias

PowerShell lets you define one or more aliases both to cmdlets and to parameters of a cmdlet. The Flavor parameter, for example, defines two aliases. With the following code you could invoke Get-Gizmo -Flavor or Get-Gizmo -Aroma or Get-Gizmo -JeNeSaisQuoi.

Standard PowerShell documentation does little to document those aliases automatically. It is up to the developer who is writing the documentation comments to mention the alias as was done, for example, with the File parameter for Get-ChildItem and its alias af:

What if you knew the alias, -af, but did not know the actual parameter name, and wanted to get help? If you try Get-Help Get-ChildItem -Param af, PowerShell will simply report that it does not know of any such parameter. Fear not! XmlDoc2CmdletDoc makes this more convenient for you and your users. It essentially promotes each alias to be a first-class parameter with respect to the generated help. Excerpting the help shown earlier, you will see that both the Flavor parameter and its aliases are documented identically (with the one exception that each alias explicitly identifies itself as an alias).

You automatically get a second benefit as well. You can now ask for help on a parameter using either the actual parameter name or any of its aliases; each of these commands will yield the same help text!

Parameter Default Values

Often you want to define a default value for a given parameter. When writing a scripted cmdlet (i.e. a cmdlet written in PowerShell rather than C#), this is straightforward to do: just supply a default value in the function signature:

When writing regular C# methods, you could provide default values in a similar fashion, but not so when writing a compiled cmdlet (i.e. a cmdlet written in C#). Here, you typically create a class deriving from Cmdlet (or PSCmdlet) wherein each parameter is defined as a property, and the main processing of the cmdlet is done in the overridden ProcessRecord method (and its ilk). So the task, then, is how to provide a default value to a property in a way that the documentation generator will recognize it. It turns out to be actually quite straightforward once you know how: simply provide a backing field for a property that is initialized at compile time. You can see this done for the Quantity property in our cmdlet sample; here is the relevant portion of code:

The default value manifests in the documentation thus:

But the story does not end there! Consider the Flavor parameter again-it lacks a backing field…

… and yet the documentation yields a default value:

And if you add these other parameters, all without backing fields…

…here’s what the documentation yields (I’ve filtered the output to just show the defaults for each):

As you may have surmised, if you do not use a backing field to explicitly provide a default value then the compiler default is used: zero for an integer, false for a Boolean, empty string for a string, zero for a DateTime, and so forth. So why did the Flavor parameter (of type FlavorTypes) show a default of Chocolate? Hearken back to the enumerated FlavorType definition:

As it turns out, enumerated types map to the set of integers beginning with 0. Thus Chocolate is really equivalent to 0, but since it is an enumerated type, the documentation nicely displays its enumerated label. To expose this mechanism, force the FlavorTypes to start with something other than 0, e.g.

Then the default in the documentation would show an actual 0, because there is now no label in the enumerated type that corresponds to 0.

Final note: you cannot really know from the documentation what the default value is when it is blank: in the case of the string parameter above it is an empty string, but for the Container parameter above it is null!

Input Parameters

You are likely to be familiar with piping objects from one cmdlet to another. When you write your own cmdlets, you can make specific parameters receive pipeline input using either the ValueFromPipeline property (which accepts a value of the same type expected by the parameter), or the ValueFromPipelineByPropertyName property (which accepts a value from a property of the input object of the same name as the parameter). Here are the salient portions of the sample cmdlet showing these in use on several parameters. Note that some have documentation comments and some do not. Some of those doc-comments are of type description, and some of type inputType. Some of the parameters are built-in .NET objects but some are custom objects. I’ve also included the custom Container class definition for discussion as well.

Of course, all parameters, pipeline-able or not, are listed in the Parameters section of the documentation. But those that may receive input from the pipeline are also listed separately in the Inputs section. Here is what XmlDoc2CmdletDoc produces for those two sections, again compressed to show just the relevant portions.

Each of these five parameters is a different case. Study the code, comparing to the output, and you will discern the following:

• If a parameter is decorated with a description paragraph, that text appears in the Parameters section. [Flavor, SomeString]
• If a parameter lacks a description paragraph, that parameter has no descriptive text in the Parameters section. [SomeSwitch, SomeDateTime, MyContainer]
• If a parameter is decorated with an inputType paragraph, that text appears in the Inputs section. [SomeString, SomeDateTime]
• If a parameter lacks an inputType paragraph but has a description paragraph, that text appears in the Inputs section. [Flavor]
• If a parameter lacks both an inputType and a description paragraph, then the description paragraph of the parameter’s type appears in the Inputs section. [MyContainer]
• If a parameter lacks both an inputType and a description paragraph, and the parameter’s type lacks a description paragraph (either because it is a .NET type or a custom type lacking a description paragraph), then that parameter has no descriptive text in the Inputs section. [SomeSwitch]

Output Parameters

Just as the Inputs section documents those parameters that may be received via the pipeline, the Outputs section documents those parameters that may be transmitted on to the next cmdlet in the pipeline. Unique to outputs, though, the crucial point to know is that the compiler does not validate what you specify as being the actual return type! That is, the compiler validates that the argument to the OutputType attribute is a valid, known type. But it does not validate that your cmdlet is, in fact, returning objects of that type; and, if you think about it, that makes sense because a cmdlet does not have a method signature specifying its inputs and outputs. The inputs are simply the public properties, and the outputs are whatever objects are returned from the base.WriteObject() call in your cmdlet (deriving from either Cmdlet or PSCmdlet). And you are even at liberty to return objects of different types in successive calls to WriteObject. Get-ChildItem, for example returns FileInfo objects and DirectoryInfo objects in a single invocation. You will see this reflected in the Outputs section of Get-Help:

Thus, take care that your OutputType values are accurate as you maintain your code over time, and remember that OutputType exists solely for the benefit of editors (for Intellisense) and documentation generators.

As far as documentation usage, decorate the cmdlet class with the OutputType attribute, as you saw in the previous article:

But another important point here is that XmlDoc2CmdletDoc can give you enhanced output (compared to standard .NET cmdlets) if you attach doc-comments to your return type–Gizmo in the example above:

Your generated Outputs section will then list the return type you specified with OutputType along with the description taken from that type itself:

That works well for your custom types. However, if your return type is a standard .NET class-which would not have the appropriate description paragraphs-then the help text will have only the type name with no description.

Summary

With the advent of XmlDoc2CmdletDoc, what used to be an arduous, tedious, and error-prone task of assembling documentation for PowerShell cmdlets has become much easier. XmlDoc2CmdletDoc brings the experience of documenting cmdlets much closer to that of both (a) documenting any other C# API, and (b) documenting scripted cmdlets (i.e. those written in PowerShell itself). In both of these cases you put the documentation comments right alongside the code, greatly reducing the maintenance hassle.

Furthermore, XmlDoc2CmdletDoc provides several enhancements to standard PowerShell documentation:

• Each custom type in the Outputs section includes a description.
• The Syntax section includes possible values for enumerated types*.
• The Parameter section includes possible values for enumerated types*.
• Aliases are documented automatically in the Parameters section*.
• Aliases are treated as first-class parameters so you can ask for help on an alias*.
• You can optionally use a different description for a parameter in the Inputs section as you have for the Parameter section.
• Web links are automatically rendered in markdown format, for possible post-processing to live links. (This enhancement is pending, as noted earlier.)
• You can require documentation of all elements by running with the -strict flag in your build process, then abort your build if the error code is non-zero.

* The starred items are tweaks to the code base that I introduced as my colleagues and I were giving XmlDoc2CmdletDoc a good workout.

This article provides all the details you need to effectively use XmlDoc2CmdletDoc. So what are you waiting for? Help your users help themselves by giving them thorough and complete documentation!