Como Escrever Ajuda Baseada em Comentários para Scripts PowerShell

1. Ajuda Baseada em Comentários no PowerShell
2. Palavras-Chave Baseadas em Comentários no PowerShell

Este artigo demonstra como podemos escrever tópicos de ajuda baseados em comentários para scripts e funções. Usaremos palavras-chave especiais de comentário de ajuda para criar os tópicos.

Usamos o cmdlet Get-Help para exibir tópicos de ajuda baseados em comentários semelhantes aos gerados por arquivos XML.

Ajuda Baseada em Comentários no PowerShell

Ilustrada abaixo está a sintaxe para ajuda baseada em comentários.

# .<help keyword>
# <help content>

ou

<#
.<help keyword>
<help content>
#>

Escrevemos tópicos de ajuda baseados em comentários como uma série de comentários. Para marcar comentários, podemos adicionar o símbolo # no início de cada linha de comentário ou usar <# e #> para criar um bloco de comentários.

O console registrará as linhas dentro do bloco de comentários como comentários.

Usamos palavras-chave especiais para definir cada seção de um tópico de ajuda baseado em comentários. As palavras-chave começam com um . e não diferenciam maiúsculas de minúsculas.

Aqui está um exemplo:

<#
.Description
Get-Clipboard fetches the content of our clipboard in the session.
#>

No exemplo acima, a palavra-chave .Description marca o comentário como a descrição da nossa função.

Um bloco de comentários deve ter pelo menos uma palavra-chave. Algumas palavras-chave aparecem apenas uma vez, enquanto outras não têm um limite.

O conteúdo de uma palavra-chave deve começar na linha imediatamente após a palavra-chave e não tem um limite.

Ao adicionar ajuda baseada em comentários para funções, você pode adicioná-los em qualquer uma das três localizações discutidas abaixo.

1. No início do corpo da função.
2. No final do corpo da função.
3. Antes da palavra-chave function. Separados por não mais de uma linha em branco.

Exemplos:

function Get-Function
{
<#
.<help keyword>
<content>
#>

  # function logic
}

ou

function Get-Function
{
   # function logic

<#
.<help keyword>
<content>
#>
}

ou

<#
.<help keyword>
<content>
#>
function Get-Function { }

A ajuda baseada em comentários para scripts pode aparecer no início do script ou no final. Aqui estão alguns exemplos:

<#
.<help keyword>
<content>
#>

function Get-Function { }

ou

function Get-Function { }

<#
.<help keyword>
<content>
#>

Palavras-Chave Baseadas em Comentários no PowerShell

Listadas abaixo estão as palavras-chave válidas de ajuda baseada em comentários. Elas podem aparecer em qualquer ordem e não diferenciam maiúsculas de minúsculas.

.SYNOPSIS

Esta é uma descrição curta da função ou script. A palavra-chave deve aparecer apenas uma vez em cada tópico.

.DESCRIPTION

Esta é uma descrição detalhada de uma função ou script. Usamos apenas uma vez em cada tópico.

.PARAMETER

Isso descreve os parâmetros no seu script ou função. Adicionamos uma palavra-chave .PARAMETER para cada parâmetro em nossos scripts ou funções.

.PARAMETER <Parameter-Name>

As palavras-chave de parâmetro não seguem uma ordem rígida no bloco de comentários. A sintaxe dos parâmetros no script ou função determinará a ordem no tópico de ajuda.

Você pode mudar a ordem mudando a sintaxe.

Podemos especificar o conteúdo da palavra-chave de parâmetro adicionando um comentário no nosso função ou script. Este comentário deve preceder o nome da variável do parâmetro.

O PowerShell prioriza a descrição associada à palavra-chave do parâmetro sobre o comentário de sintaxe onde ambos são usados.

<#
.SYNOPSIS
    Brief description
#>
function Noun-Verb {
    [CmdletBinding()]
    param (
        # It is the same as .Parameter
        [string]$CompName
    )
    # Logic
}

.EXAMPLE

Inclua um comando de exemplo que empregue o script ou função. Podemos incluir esta palavra-chave para todos os exemplos no nosso script ou função.

.INPUTS

Esses são os objetos .NET que podemos canalizar para nosso script ou função. Podemos adicionar uma descrição para os objetos de entrada.

.OUTPUTS

Esses são os objetos .NET que nosso cmdlet retorna. Podemos adicionar uma descrição para os objetos retornados.

.NOTES

Essas são quaisquer informações adicionais sobre o script ou função. As informações podem incluir a data em que foi codificado, o nome da função ou o nome do criador.

.LINK

Esses são os tópicos relacionados.

Aqui está um exemplo de ajuda baseada em comentários para uma função:

Em conclusão, podemos adicionar ajuda baseada em comentários em funções ou scripts, colocando-os em um bloco de comentários. Ao adicionar tópicos de ajuda, use a palavra-chave que discutimos acima e lembre-se de onde colocar os blocos de comentários para scripts e funções.