How do you correctly document Powershell functions? - powershell

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?

Answer 1

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