如何正确记录Powershell函数？

我是Powershell的新手，尽我所能，它在Python中没有类似于PEP8/PEP484的东西。我从微软和第三方指南中找到了Posh Code。我编写了以下函数：

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

  #>
}

---

据我所知，根据指南，这是正确的，但在我看来，它看起来非常愚蠢的描述在最后。对于Powershell，我是否缺少一套编码风格指南，或者这是正确的？您是否应该删除不适用于函数的字段？例如，我没有输入。我应该完全删除它吗？

这叫做基于评论的帮助

您有3个选项可用于放置文档：

•在功能体的开头

•在功能体的末尾

•在函数关键字之前。不能有多个空白 函数帮助的最后一行与函数之间的行 关键词

因此，您可以轻松地将它们放在函数的顶部（内部或外部）：

函数调用验证{ < 提要 ... > 或

< 提要 ... > 函数调用验证{

---

并非所有部分都是必需的，您可以只包含您想要的任何部分。这取决于您的用例和公司指南。我通常至少包含.SYSNOPSIS、.DESCRIPTION、.parameters和.EXAMPLES。

这称为基于注释的帮助

您有3个选项可用于放置文档：

•在功能体的开头

•在功能体的末尾

•函数关键字前。不能有多个空白 函数帮助的最后一行与函数之间的行 关键词

因此，您可以轻松地将它们放在函数的顶部（内部或外部）：

函数调用验证{ < 提要 ... > 或

< 提要 ... > 函数调用验证{ 并非所有部分都是必需的，您可以只包含您想要的任何部分。这取决于您的用例和公司指南。我通常至少包含.SYSNOPSIS、.DESCRIPTION、.parameters和.EXAMPLES