Indentation on Comment-Based help

[ryanspletzer]

What's the stance on the indentation on comment-based help?

Personally, I left-align the comment-based help so I can get the most line length out of it, and I also try to keep comment-based help under 114 characters long else I see weird line wrapping issues with Get-Help. (I know using PlatyPS would avoid some of these issues, but one doesn't always go to those lengths for every script, probably only for modules.)

[Jaykul]

This isn't a prescription, but I generally do one of these two ways:

function New-PSCredential {
    <#
    .Synopsis
        Creates a new PSCredential with the specified properties
    #>

Or

function Export-Theme {
    <#
        .SYNOPSIS
            Exports a theme to a file
    #>

I'm still debating whether:

• The help keywords should be ALL CAPS (they're shown that way in the help output, and it's easier to spot in editors that don't do syntax highlighting of comments)
• The help keyword blocks need to be indented from the <# comment block.

I will admit that my main reason for indenting is to control code folding in VS Code. VS Code bases the folding of those lines on the indentation. If I don't indent the .Synopsis line further than the <# comment, then you can fold/hide the whole comment block, but not each section of the help...

[ryanspletzer]

Re: ALL CAPS, that's what I do.

This is what mine typically look like:

function Invoke-Something {
<#
.SYNOPSIS
    My synopsis.

#>

I keep the <# comment block left align and same with the help keywords, and I also have a column marker at 114 so that I don't go further than that with help. (Though I suppose I could just set that to 118 and achieve the same if I indent the comment block.)

That's interesting you mention about being able to fold a section of help. I'm trying that now in VS Code and I don't see the option to fold a section of help...

[Jaykul]

Yeah, that's due to changes from the PowerShell extension. I've asked for this to be fixed, it's because the syntax-based code-folding doesn't care about the help comments...

Without that, we get this:

With it, we only get this:

[iRon7]

FYI: not so known but also to consider, the fact that it is valid to use single comment lines for your help:

function Read-HtmlTable {
# .SYNOPSIS
#     Reads a HTML table
# .DESCRIPTION
#     Scrapes (extracts) a HTML table from a string or the internet location
# .INPUTS
#     String or Uri
# .OUTPUTS
#     PSCustomObject[]
# .PARAMETER InputObject
#     The html content (string) that contains a html table.
#     If the string is less than 2048 characters and contains a valid uri protocol, the content is downloaded
#     from the concerned location.
}

[Jaykul]

FYI: not so known but also to consider, the fact that it is valid to use single comment lines for your help:

This is really well known, among those who've been around since version 1 😉 it used to be the only way to do it, and there was a little debate about adding block comments. We particularly recommend block comments for documentation (it makes it easier to edit, and it improves code-folding of the documentation in most editors).