Generating Help from Script Files

Topics: Developer Forum
Coordinator
Feb 26, 2007 at 5:23 AM
I've been experimenting lightly with something like this:

# ---------------------------------------------------------------------------
### <function name="Add-PathVariable">
### <author>Jachym</author>
### <synopsis>
### This function adds the specified paths to the specified environment variable.
### </synopsis>
### <usage>Add-PathVariable Path C:\Bin,C:\Users\John\Bin</usage>
### </function>
# ---------------------------------------------------------------------------

which is used to create a file like this:

<functions file="C:\Users\Keith\PowerShellCX\Branches\Release\1.1\Src\PscxSnapin\Profile\GenericFunctions.ps1">
	<function name="Add-PathVariable">
		<author>Jachym</author>
		<synopsis>
			This function adds the specified paths to the specified environment variable.
		</synopsis>
		<usage>Add-PathVariable Path C:\Bin,C:\Users\John\Bin</usage>
	</function>
</functions>

Which can then of course be used to auto-generate text for the about_Pscx.help.txt file. BTW I'm not sold on really any part of the PS1 file format or the generated XML. I think it is also likely that you would want to specify multiple usage elements. Thoughts?
Developer
Feb 26, 2007 at 3:31 PM
Very nice! I'd prefer to stick with the naming we use for cmdlets, that is Description, DetailedDescription and Examples...
Coordinator
Feb 26, 2007 at 8:43 PM
Yeah that reads better. For this (filling in about_Pscx.help.txt) I don't think we need to distinguis between Description and DetailedDescription. You also prefer the Pascal-cased element names?
Developer
Feb 27, 2007 at 5:19 PM
Yeah, Description is enough for a function. I like camelCase and PascalCase both the same for xml, but all the ps1xml files are PascalCased already, so I only followed their convention.