6 ways of breaking comment-based help in powershell

Green ManA quick note on the different ways I’ve found of breaking the comment-based help in Powershell. I’ve only started playing with it today. I’ve not verified all of these – I’ll do so when time allows
[toc]

Leave the ‘.’ off of a label

If I leave out the full-stop on one of the labels:

SYNOPSIS
Lists services on specified server which are set as autostart but are currently stopped

.DESCRIPTION
Uses wmi to get services into�

It breaks the whole of the help:

PS C:> help sstop

show-stoppedservices [[-MyServer]]

Have a function with the same name as a script

If my function name is kept in a ps1 file with the same name as the function, then the help subsytem just shows the different items. If I rename the .ps1 file as follows:

move function-show-stoppedservices.ps1 show-stoppedservices.ps1

And I try to get help on the function (using the full function name – the alias would be OK):  

PS C:> help show-stoppedservices 
Name                     Category   Synopsis 
----                     --------   -------- 
show-stoppedservices     Function   Lists services on specified serv... show-stoppedservices.ps1 Extern...  show-stoppedservices.ps1 ...

Don’t name the parameter correctly

If you mis-spell the name of the parameter in the Help text, then you’ll lose any description that you add in, obviously enough:

.PARAMETER NotMyServer
Specify the remote server. If null tells you about wherever you are
running

Code:
Param ( [String] $MyServer = "." )

Powershell will still give you the definition of the parameter but you lose the help text.

help show-stoppedservices -parameter MyServer

type                       name                       parameterValue
----                       ----                       --------------
@{name=String}             MyServer                   String

Putting this right:

.PARAMETER MyServer

Allows Powershell to use your help:

help show-stoppedservices -parameter MyServer

type                name                parameterValue      description
----                ----                --------------      -----------
@{name=String}      MyServer            String              {@{Text=Specify ...

Leaving out the parameter

I was using a template which looked like this

.PARAMETER 

.EXAMPLE

I’ve found that having the Parameter tage without having a Parameter name in place breaks _all_of the help.

So….I had lots of content in the description, synopsis etc, but it was invisible to get-help until I filled in the Parameter (or, presumably, deleted the Parameter tag)

Not (re-) sourcing the function! 🙂

If you change the comment-based help you have to re-source the function for the change to show up

Using the REMARKS section

It may be I just got this wrong, but I thought I’d try using the ‘remarks’
section to keep track of what needs to be done to the script.

This seemed to naus it all up:

.REMARKS
Todo: Check the serverinstance exists and is running
Todo: Check the database exists

….although perhaps it was something else.

Not having the help inside the brackets

Another muck up on my part. I had a couple of little functions to turn debug on and off:

function dbon
<#
.SYNOPSIS
    Sets debug on
#>
{. set-debug on}

This doesn’t work. The comment-based help has to be inside the function definition i.e. inside the curly brackets

function dbon {
<#
.SYNOPSIS
    Sets debug on
#>
. set-debug on}

““

Advertisements