How do you correctly document Powershell functions?

Question

I'm new to Powershell and as best as I can find it doesn't have anything like PEP8/PEP484 in Python. I found this document from Microsoft and this third party guide from Posh Code. I have written the following function:

function Invoke-Authenticate {

  [CmdletBinding()]
  param (
      [Parameter(Mandatory)]
      [string] 
      # IP address of the OME server
      $Ip,

      [Parameter(Mandatory)]
      # Credentials for the OME server
      [pscredential] $Credentials
  )

  $SessionUrl  = "https://$($IpAddress)/api/SessionService/Sessions"
  $Type        = "application/json"
  $UserDetails = @{"UserName"=$Credentials.username;"Password"=$Credentials.GetNetworkCredential().password;
                   "SessionType"="API"} | ConvertTo-Json
  $Headers     = @{}

  try {
    $SessResponse = Invoke-WebRequest -Uri $SessionUrl -Method Post -Body $UserDetails -ContentType $Type `
                                      -SkipCertificateCheck
    if ($SessResponse.StatusCode -eq 200 -or $SessResponse.StatusCode -eq 201) {
      # Successfully created a session - extract the auth token from the response
      # header and update our headers for subsequent requests
      $Headers."X-Auth-Token" = $SessResponse.Headers["X-Auth-Token"]
    } else {
      Write-Error "OME did not return a 200 or 201 status code. Received $($SessResponse.StatusCode).
      We are unsure why this happened."
    }
  }
  catch [Microsoft.PowerShell.Commands.HttpResponseException] {
    Write-Error "There was a problem authenticating with OME. Are you sure you have the right username and password?"
    return $null
  }
  catch [System.Net.Http.HttpRequestException] {
    Write-Error "There was a problem connecting to OME. Are you sure you have the right IP and that it is available?"
    return $null
  }

  return $Headers

  <#
    .SYNOPSIS
    Authenticates with OME and creates a session

    .DESCRIPTION
    Authenticates with OME and creates a session

    .PARAMETER Ip
    IP address of the OME server

    .PARAMETER Credentials
    Credentials for the OME server

    .INPUTS
    None. You cannot pipe objects to Invoke-Authenticate.

    .OUTPUTS
    hashtable. The Invoke-Authenticate function returns a hashtable with the headers resulting from authentication 
               against the OME server

  #>
}

As far as I can tell based on the guides that is correct however, it looks very goofy to me to have the description at the end. Are there set coding style guidelines I'm missing for Powershell or is this correct? Are you supposed to just delete the fields not applicable for a function? For example I have no .INPUTS. Should I just delete that entirely?

marsze · Accepted Answer · 2022-09-28 15:48:55Z

It's called "comment-based help" (about_Comment_Based_Help)

You have 3 options where to put the documentation:

• At the beginning of the function body.

• At the end of the function body.

• Before the function keyword. There cannot be more than one blank line between the last line of the function help and the function keyword.

So, you can easily put them at the top of your function (either inside or outside):

function Invoke-Authenticate {
<#
.SYNOPSIS
...
#>

or

<#
.SYNOPSIS
...
#>
function Invoke-Authenticate {

Not all sections are required, you can just include whichever you want. It depends on your use-case and company guidelines. I usually include at least:

.SYNOPSIS

.DESCRIPTION

.PARAMETERS

.EXAMPLES

Another useful thing, if you happen to have a company internal help page (like a wiki), you can add a link:

.LINK
https://wiki.my-company.com/my-module/help

@asheroto The help page contains no recommendation. Personally, I prefer it before the function, just as you would do with comments.

Ethan H · Accepted Answer · 2025-02-26 23:09:24Z

In the Posh Code site, their PowerShell Practice and Style guide, Don Jones, M. Penny, C. Perez, J. Bennett and the PowerShell Community suggest function documentation best practice places the comment-based help inside and at the top of the function it describes. Inside, so it does not get separated from the function, and at the top so developers see them and remember to update them.

In order to ensure that the documentation stays with the function, documentation comments should be placed INSIDE the function, rather than above. To make it harder to forget to update them when changing a function, you should keep them at the top of the function, rather than at the bottom.

Documentation and Comments

Collectives™ on Stack Overflow

How do you correctly document Powershell functions?

2 Answers 2

2 Comments

Comments

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

2 Comments

Comments

Related