Documenting PowerShell script code

The Macaw Solutions Factory contains a lot of PowerShell script code. A lot of the code is documented, but it is not documented in a consistent way because there were no documentation standards available for PowerShell 1.0, we only had the very complex XML based MAML documentation standard that was not useable for inline documentation.

With the (upcoming) introduction of PowerShell 2.0, a new more readable documentation standard for PowerShell code is introduced. I did not find any formal documentation on it, only examples on the PowerShell team blog. There is even a script to create a weblog post out of a script containing this documentation format. See http://blogs.msdn.com/powershell/archive/tags/Write-CommandBlogPost/default.aspx for this script and an example of the documentation format.

The new documentation format uses a PowerShell 2.0 feature for multi-line comments:

<#
:
\#>

Because this is not supported in PowerShell 1.0 , we will write the documentation as follows to remain compatible:

\#<#
\#:
\##>

This will allows us to change the documentation by removing the superfluous # characters when the code-base is moved over to PowerShell 2.0 when it is released.

Documenting PowerShell scripts

Scripts can be provided with documentation in the following format:

#<#
#.Synopsis
#	Short description of the purpose of this script
#.Description
#	Extensive description of the script
#.Parameter X
#    Description or parameter X
#.Parameter Y
#    Description or parameter Y
#.Example
#	First example of usage of the script
#.Example
#	Second example of usage of the script
##>
param
(
	X,
	Y
)
:

function MyFunction
{
#<#
#.Synopsis
#	Short description of the purpose of this function
#.Description
#	Extensive description of the function
#.Parameter X
#    Description or parameter X
#.Parameter Y
#    Description or parameter Y
#.Example
#	First example of usage of the function
#.Example
#	Second example of usage of the function
##>
param
(
X,
Y
)
:
}


:

Automatically generating documentation

The next step is to automatically generate documentation on all our scripts based on the new documentation format.

The best approach will possibly be to use PowerShell 2.0 to actually generate the documentation, because using PowerShell 2.0 we can parse PowerShell code. We can easily determine the functions and their parameters.

A nice project for the future.

No Comments