Ajuda baseada em comentários

A documentação é uma parte essencial de qualquer código, e no PowerShell, a ajuda baseada em comentários é a maneira nativa de documentar funções e scripts. Em vez de manter a documentação em arquivos separados, você pode incorporá-la diretamente no código, usando blocos de comentários especiais que o PowerShell reconhece e transforma em páginas de ajuda completas, acessíveis via Get-Help. Nesta aula, vamos explorar como criar essa documentação, quais seções são importantes e como garantir que sua ajuda seja clara e útil para outros usuários (ou para você mesmo no futuro).

Dominar a ajuda baseada em comentários é uma habilidade que diferencia um programador iniciante de um profissional. Além de melhorar a legibilidade do código, ela permite que seus scripts sejam utilizados por outras pessoas sem que precisem abrir o código-fonte para entender o que cada função faz. Vamos ver na prática como documentar funções, usar as palavras-chave especiais e integrar tudo com o Get-Help.

Documentando funções

Para documentar uma função, você deve colocar um bloco de comentário especial logo antes da declaração da função. Esse bloco começa com <# e termina com #>. Dentro dele, você pode usar várias palavras-chave que começam com um ponto (por exemplo, .SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE, etc.) para estruturar a ajuda.

O PowerShell reconhece esses blocos e constrói um objeto de ajuda que pode ser exibido com Get-Help. É importante que o bloco de comentário seja colocado imediatamente antes da função (ou script) — não pode haver linhas em branco ou outros comandos entre o comentário e a declaração da função.

Aqui está um exemplo simples de uma função documentada:

function Get-Saudacao {
    <#
    .SYNOPSIS
    Retorna uma saudação personalizada.

    .DESCRIPTION
    Esta função recebe um nome e retorna uma saudação amigável.

    .PARAMETER Nome
    O nome da pessoa a ser saudada.

    .EXAMPLE
    Get-Saudacao -Nome "Maria"
    Retorna "Olá, Maria!"
    #>
    param (
        [string]$Nome
    )
    "Olá, $Nome!"
}

Observe que usamos .SYNOPSIS para um resumo curto, .DESCRIPTION para uma explicação mais detalhada, .PARAMETER para documentar cada parâmetro e .EXAMPLE para mostrar um exemplo de uso. Essas são as seções mais comuns, mas existem outras como .INPUTS, .OUTPUTS, .NOTES, .LINK, etc.

Quando você executa Get-Help Get-Saudacao, o PowerShell exibirá essas informações formatadas. Se você adicionar o parâmetro -Full, verá todas as seções preenchidas.

.SYNOPSIS, .EXAMPLE

A seção .SYNOPSIS é obrigatória e deve conter uma descrição curta e objetiva da função, geralmente uma frase. Ela aparece na primeira linha da ajuda, junto com o nome da função. Por exemplo:

.SYNOPSIS
Retorna a data atual no formato dd/MM/yyyy.

A seção .EXAMPLE é extremamente importante, pois mostra como usar a função na prática. Você pode incluir vários exemplos, cada um com uma descrição opcional e o comando propriamente dito. O PowerShell reconhece o texto após .EXAMPLE como uma entrada de exemplo, e se houver mais de um, eles são numerados automaticamente.

Exemplo com vários exemplos:

function Get-DataFormatada {
    <#
    .SYNOPSIS
    Retorna a data atual formatada.

    .EXAMPLE
    Get-DataFormatada
    Retorna a data atual no formato dd/MM/yyyy.

    .EXAMPLE
    Get-DataFormatada -Formato "yyyy-MM-dd"
    Retorna a data atual no formato ISO (yyyy-MM-dd).
    #>
    param(
        [string]$Formato = "dd/MM/yyyy"
    )
    Get-Date -Format $Formato
}

Nesse caso, Get-Help Get-DataFormatada -Examples exibirá os dois exemplos com seus respectivos comandos e descrições. É uma boa prática fornecer pelo menos um exemplo para cada função, mostrando o uso mais comum.

Integração com Get-Help

O cmdlet Get-Help é a principal ferramenta para acessar a documentação no PowerShell. Ele lê os blocos de comentário e exibe a ajuda formatada. A integração é automática: se uma função tem um bloco de comentário válido, Get-Help o reconhece.

Você pode usar vários parâmetros com Get-Help para visualizar diferentes partes da ajuda:

• -Full exibe toda a documentação, incluindo parâmetros, exemplos, notas, etc.
• -Detailed exibe a ajuda com mais detalhes que o padrão, incluindo descrições de parâmetros.
• -Examples exibe apenas os exemplos.
• -Parameter NomeParametro exibe apenas a documentação de um parâmetro específico.

Exemplo de uso:

Get-Help Get-Saudacao -Full

Além disso, o PowerShell procura a ajuda em várias fontes: primeiro no bloco de comentário da própria função, depois em arquivos de ajuda externos (XML) e, em último caso, em módulos. Para funções que estão em módulos, é possível criar arquivos de ajuda externos, mas a abordagem baseada em comentários é mais simples e recomendada para a maioria dos casos.

Outro ponto importante: se você usa o ISE ou o Visual Studio Code com a extensão PowerShell, a ajuda baseada em comentários também é usada para o IntelliSense e para exibir informações ao passar o mouse sobre a função.

Exemplos

Vamos criar uma função mais complexa e documentá-la completamente, mostrando várias seções.

function Set-Configuracao {
    <#
    .SYNOPSIS
    Define uma configuração em um arquivo XML.

    .DESCRIPTION
    A função Set-Configuracao permite modificar um valor específico em um arquivo de configuração XML.
    Ela aceita o caminho do arquivo, a chave e o novo valor. Se a chave não existir, ela será criada.

    .PARAMETER Caminho
    Caminho completo do arquivo XML.

    .PARAMETER Chave
    Nome da chave a ser configurada.

    .PARAMETER Valor
    Novo valor a ser atribuído.

    .EXAMPLE
    Set-Configuracao -Caminho "C:\Config\app.xml" -Chave "Timeout" -Valor "30"
    Define o valor da chave Timeout como 30 no arquivo especificado.

    .EXAMPLE
    Set-Configuracao -Caminho "C:\Config\app.xml" -Chave "NovaChave" -Valor "NovoValor"
    Se a chave NovaChave não existir, ela é criada com o valor NovoValor.

    .NOTES
    Autor: Seu Nome
    Data: 2025-01-01
    Requer PowerShell 5.1 ou superior.

    .LINK
    https://learn.microsoft.com/powershell/
    #>
    param(
        [Parameter(Mandatory)]
        [string]$Caminho,
        [Parameter(Mandatory)]
        [string]$Chave,
        [Parameter(Mandatory)]
        [string]$Valor
    )
    # Suponha que a implementação esteja aqui
    Write-Host "Configuração $Chave = $Valor aplicada em $Caminho"
}

Agora, se você executar Get-Help Set-Configuracao -Full, verá uma ajuda completa com todas as seções. Observe que usamos .NOTES para informações adicionais e .LINK para referências externas.

Outro recurso interessante é a capacidade de documentar parâmetros com atributos, como [Parameter(Mandatory)], que também aparecem na ajuda.

Além disso, você pode documentar scripts inteiros (arquivos .ps1) da mesma forma, colocando o bloco de comentário no início do arquivo. Nesse caso, a ajuda é exibida quando você executa Get-Help .\script.ps1.

Boas práticas e observações finais

Ao criar ajuda baseada em comentários, siga estas boas práticas:

• Sempre inclua pelo menos .SYNOPSIS e .EXAMPLE.
• Use .DESCRIPTION para explicar o que a função faz e por que é útil.
• Documente todos os parâmetros com .PARAMETER, incluindo tipos e valores padrão.
• Forneça exemplos variados, incluindo casos com parâmetros opcionais.
• Mantenha a documentação atualizada quando alterar a função.
• Use .NOTES para informações como autor, data e requisitos.
• Use .LINK para referências a documentação relacionada.

Lembre-se de que a ajuda baseada em comentários não substitui a necessidade de testes e código limpo, mas é uma ferramenta poderosa para tornar seus scripts mais profissionais e fáceis de usar.

Referências

• about_Comment_Based_Help - Documentação oficial da Microsoft
• Get-Help - Microsoft Learn
• PowerShell 101: Functions - Microsoft Learn
• Writing Help for Functions - Microsoft Learn
• Writing Help for Scripts - Microsoft Learn
• Creating Custom Help Files - Microsoft Learn

Exercícios

1. Exercício 1: Crie uma função chamada Get-InfoSistema que retorne o nome do computador e a versão do sistema operacional. Documente-a com .SYNOPSIS, .DESCRIPTION, .EXAMPLE e .NOTES.

Ver resposta

function Get-InfoSistema {
    <#
    .SYNOPSIS
    Retorna informações básicas do sistema.

    .DESCRIPTION
    Obtém o nome do computador e a versão do sistema operacional.

    .EXAMPLE
    Get-InfoSistema
    Retorna algo como:
    Computador: MEU-PC
    SO: Microsoft Windows 10 Pro 10.0.19045

    .NOTES
    Autor: Aluno
    Data: 2025-01-01
    #>
    $info = [PSCustomObject]@{
        Computador = $env:COMPUTERNAME
        SO = (Get-CimInstance Win32_OperatingSystem).Caption
    }
    $info
}

Ver resposta

function Get-Saudacao {
    <#
    .SYNOPSIS
    Retorna uma saudação personalizada.

    .DESCRIPTION
    Dado um nome, retorna uma saudação amigável.

    .PARAMETER Nome
    O nome da pessoa a ser saudada.

    .EXAMPLE
    Get-Saudacao -Nome "Maria"
    Retorna "Olá, Maria!"
    #>
    param(
        [Parameter(Mandatory)]
        [string]$Nome
    )
    "Olá, $Nome!"
}

Ver resposta

Ver resposta

Ver resposta

function Add-Numeros {
    <#
    .SYNOPSIS
    Soma dois números.

    .DESCRIPTION
    Retorna a soma de dois números fornecidos.

    .PARAMETER Numero1
    Primeiro número.

    .PARAMETER Numero2
    Segundo número.

    .EXAMPLE
    Add-Numeros -Numero1 5 -Numero2 3
    Retorna 8.

    .EXAMPLE
    Add-Numeros -Numero1 10 -Numero2 20
    Retorna 30.

    .OUTPUTS
    System.Int32
    #>
    param(
        [Parameter(Mandatory)]
        [int]$Numero1,
        [Parameter(Mandatory)]
        [int]$Numero2
    )
    $Numero1 + $Numero2
}