How do you correctly document Powershell functions?

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?

Solution

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
...
#>

<#
.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