Newlines in comment-based help

This topic contains 0 replies, has 1 voice, and was last updated by Profile photo of Forums Archives Forums Archives 5 years, 3 months ago.

  • Author
    Posts
  • #5022

    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!

You must be logged in to reply to this topic.