Author Posts

January 1, 2012 at 12:00 am

by MattG at 2012-08-19 13:50:33

Is there any way to trick PowerShell into displaying newlines in comment-based help? As an example, here's a sample function

[script=powershell]function Test-Function
{
< #
.SYNOPSIS

line 1

line 2

line 3

.DESCRIPTION

line 1

line 2

line 3
#>

Write-Output "What you see is not what you get!"

}[/script]
This produces the following help output:

NAME
TestFunc

SYNOPSIS
line 1
line 2
line 3

SYNTAX
TestFunc []

DESCRIPTION
line 1
line 2
line 3

PARAMETERS

This cmdlet supports the common parameters: Verbose, Debug,
ErrorAction, ErrorVariable, WarningAction, WarningVariable,
OutBuffer and OutVariable. For more information, type,
"get-help about_commonparameters".

INPUTS

OUTPUTS

RELATED LINKS

by poshoholic at 2012-08-19 14:04:02

Interesting. I just ran a few quick tests. In PowerGUI, PowerSE, and PowerShell ISE I get the help with spaces between the lines. But in the native PowerShell console, any line containing nothing but whitespace is stripped from the comment-based help. And it doesn't make a difference whether I put your test function in a file or if I use it ad-hoc; I always get the same results in each host. Maybe this is a limitation for the native PowerShell console. Or maybe it's just a bug. Xml-based maml help will allow you to do this. It can be more work to set up, but it can also be less work if you have the right tools.

by MattG at 2012-08-19 14:19:21

Thanks, Kirk. Sorry. I should have specified the console.

Speaking of tools, I've encountered several PS MAML generators out there. Is there any one in particular that you recommend?

by poshoholic at 2012-08-19 15:38:33

I have a function in part of a module that I'm working on called Update-MamlHelp that will generate/update maml help for one or more commands or an entire module, with TODO's in the xml for anything that you actually need to update. I recommend that one. I could send you a pre-release version of that module if you want to give it a spin, and maybe share your feedback. Email me if that interests you and I'll see if I can do a quick clean-up (was experimenting with some things that are still works-in-progress) and send you what I have so far.

by MattG at 2012-08-19 15:45:39

If it will solve my newline woes on the console, I'd love to try out the pre-release version and give my feedback!