{"id":2206,"date":"2016-04-22T00:00:00","date_gmt":"2016-04-22T00:00:00","guid":{"rendered":"https:\/\/test.simple-talk.com\/uncategorized\/unified-approach-to-generating-documentation-for-powershell-cmdlets\/"},"modified":"2016-07-26T15:06:17","modified_gmt":"2016-07-26T15:06:17","slug":"unified-approach-to-generating-documentation-for-powershell-cmdlets","status":"publish","type":"post","link":"https:\/\/www.red-gate.com\/simple-talk\/sysadmin\/powershell\/unified-approach-to-generating-documentation-for-powershell-cmdlets\/","title":{"rendered":"Unified Approach to Generating Documentation for PowerShell Cmdlets"},"content":{"rendered":"<div class=\"article-content\">\n<ul class=\"series-articles\">\n<li>Part 1: <a href=\"https:\/\/www.simple-talk.com\/sysadmin\/powershell\/how-to-document-your-powershell-library\/\">How to Document your PowerShell Library<\/a><\/li>\n<li>Part 2: <a href=\"https:\/\/www.simple-talk.com\/dotnet\/development\/using-c-to-create-powershell-cmdlets-the-basics\/\">Using C# to Create PowerShell Cmdlets: The Basics<\/a><\/li>\n<li>Part 3: <a href=\"https:\/\/www.simple-talk.com\/dotnet\/software-tools\/documenting-your-powershell-binary-cmdlets\/\">Documenting Your PowerShell Binary Cmdlets<\/a><\/li>\n<li class=\"series-articles--active\">Part 4: Unified Approach to Generating Documentation for PowerShell Cmdlets<\/li>\n<\/ul>\n<p class=\"start\">PowerShell&#8217;s <strong>Get-Help<\/strong> cmdlet is the conduit for getting details of a cmdlet, whether that cmdlet is written in C# or in PowerShell. Thus, one needs to be able to provide content for that help when writing in either language. From its early days, PowerShell has provided full support for documentation comments (&#8220;doc-comments&#8221;) in PowerShell code: you could instrument your functions with doc-comments and <strong>Get-Help <\/strong>would use those to generate its help. Until recently though, this has been rather arduous to do in C# code. Essentially, you had to perform a laborious and error-prone process to build your own MAML documentation file: Even with custom editors built for the task, it was a chore to keep your documentation in sync with your code.<\/p>\n<p>Then in 2015,<strong> <\/strong><strong>XmlDoc2Cmd<\/strong><strong>letDoc<\/strong> came along and filled in the crucial gap: you can now instrument your C# cmdlet code just like any other C# code, and just like PowerShell code. Therefore, you can nowadays easily support <strong>Get-He<\/strong><strong>lp<\/strong> from either C# or PowerShell and keep your documentation maintained right alongside your code.<\/p>\n<p>That much allows you to feed proper details to <strong>Get-Help<\/strong> to show help for a single command. This follows in the venerable tradition of the Unix &#8220;man&#8221; command or the DOS &#8220;help&#8221; command, presenting documentation for a single command. Unlike those other environments, however, PowerShell is not just a shell language, but also a rich programming language. Therefore, PowerShell needs to be able to provide a navigable documentation tree such as is provided by Sandcastle for C# or by Javadoc for Java. To give you the same ease of use, you can use the<strong> <\/strong><strong>DocTreeGenerator<\/strong> utility, which supports this key capability for PowerShell. It supports modules written in C# or in PowerShell, or in a combination of both.<\/p>\n<p>The accompanying wallchart shows at a glance all the pieces you need to build your documentation using the above tools in concert with Visual Studio and PowerShell.<\/p>\n<p>\n        <a href=\"https:\/\/www.simple-talk.com\/content\/file.ashx?file=12790\"><img decoding=\"async\" src=\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/imported\/2407-1-5728ddc3-433a-4b82-a6dc-84f5f450b519.png\" alt=\"2407-1-5728ddc3-433a-4b82-a6dc-84f5f450b\" \/><\/a>\n    <\/p>\n<div class=\"note\">\n<p class=\"note\">To download the full sized wallchart, either click on the thumbnail above, or <a href=\"https:\/\/www.simple-talk.com\/content\/file.ashx?file=12790\">click here<\/a>.<\/p>\n<\/p><\/div>\n<\/div>\n","protected":false},"excerpt":{"rendered":"<p>Now, it is easy to provide professional-quality documentation for PowerShell cmdlets, and to keep it in sync when you make changes, whether they are written in PowerShell or C#. Whereas this has always been easy to do in PowerShell, it was always painful to do in C# or VB because it meant having to build your own MAML file. Michael completes his three-part series by summarising, in a wallchart, how to go about it. &hellip;<\/p>\n","protected":false},"author":221868,"featured_media":0,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[35],"tags":[],"coauthors":[6802],"class_list":["post-2206","post","type-post","status-publish","format-standard","hentry","category-powershell"],"acf":[],"_links":{"self":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/2206","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/users\/221868"}],"replies":[{"embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/comments?post=2206"}],"version-history":[{"count":4,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/2206\/revisions"}],"predecessor-version":[{"id":66296,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/posts\/2206\/revisions\/66296"}],"wp:attachment":[{"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/media?parent=2206"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/categories?post=2206"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/tags?post=2206"},{"taxonomy":"author","embeddable":true,"href":"https:\/\/www.red-gate.com\/simple-talk\/wp-json\/wp\/v2\/coauthors?post=2206"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}