Documenting your PowerShell API--solved!

Long has it been known how to easily document your PowerShell source code simply by embedding properly formatted documentation comments right along side your code, making maintenance relatively painless...

 

Sample Doc-Comments for PowerShell source

But if you advanced to writing your PowerShell cmdlets in C#, you have largely been on your own, either hand-crafting MAML files or using targeted MAML editors far removed from your source code. But not anymore. With the advent of Chris Lambrou's open-source XmlDoc2CmdletDoc, the world has been righted upon its axis once more: it allows instrumenting your C# source with doc-comments just like any other C# source:

csharp doc-comment sample

All of the above provides fuel for Get-Help, i.e. providing help one cmdlet at a time. But we are a civilized people; we also need a web-based version of our full custom PowerShell API. That is, a hierarchical and indexed set of Get-Help pages for all the cmdlets in our module. For this task, my own open-source effort, DocTreeGenerator, nicely fills the gap, requiring very little beyond the doc-comments described above to do the complete job.

I have written extensively on using both XmlDoc2CmdletDoc and DocTreeGenerator, and just this week, released a one-page wallchart that shows how all the pieces work together:

doc wallchart thumbnail

Here's the link to get you started on this fun journey:

Unified Approach to Generating Documentation for PowerShell Cmdlets

About the Author

Michael Sorens

Software designer/architect, application/website developer (including several open source projects), author (over 100 articles published and over 200 answers on StackOverflow), educator--see full brand page at http://cleancode.sourceforge.net/wwwdoc/about.html.