Escribir ayuda basada en comentarios para scripts de PowerShell

1. Ayuda basada en comentarios en PowerShell
2. Palabras clave basadas en comentarios en PowerShell

Este artículo demuestra cómo podemos escribir temas de ayuda basados en comentarios para scripts y funciones. Usaremos palabras clave de comentarios de ayuda especiales para crear los temas.

Usamos el cmdlet Get-Help para mostrar temas de ayuda basados en comentarios similares a los generados por archivos XML.

Ayuda basada en comentarios en PowerShell

A continuación se ilustra la sintaxis de la ayuda basada en comentarios.

# .<help keyword>
# <help content>

o

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

Escribimos temas de ayuda basados en comentarios como una serie de comentarios. Para marcar comentarios, podemos agregar el símbolo # al comienzo de cada línea de comentario o usar <# y #> para crear un bloque de comentarios.

La consola registrará las líneas dentro del bloque de comentarios como comentarios.

Usamos palabras clave especiales para definir cada sección de una ayuda de tema basada en comentarios. Las palabras clave comienzan con un . y no distinguen entre mayúsculas y minúsculas.

Aquí hay un ejemplo:

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

En el ejemplo anterior, la palabra clave .Description marca el comentario como la descripción de nuestra función.

Un bloque de comentarios debe tener al menos una palabra clave. Algunas palabras clave solo aparecen una vez, mientras que otras no tienen límite.

El contenido de una palabra clave debe comenzar en la línea inmediatamente posterior a la palabra clave y no tiene límite.

Al agregar ayuda basada en comentarios para funciones, puede agregarlas en cualquiera de las tres ubicaciones que se describen a continuación.

1. Al comienzo del cuerpo de la función.
2. Al final del cuerpo de la función.
3. Antes de la palabra clave función. Separados por no más de una línea en blanco.

Ejemplos:

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

  # function logic
}

o

function Get-Function
{
   # function logic

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

o

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

La ayuda basada en comentarios para las secuencias de comandos puede aparecer al principio o al final de la secuencia de comandos. Aquí hay unos ejemplos:

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

function Get-Function { }

o

function Get-Function { }

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

Palabras clave basadas en comentarios en PowerShell

A continuación se enumeran las palabras clave de ayuda válidas basadas en comentarios. Pueden aparecer en cualquier orden y no distinguen entre mayúsculas y minúsculas.

.SINOPSIS

Esta es una breve descripción de la función o secuencia de comandos. La palabra clave solo debe aparecer una vez en cada tema.

.DESCRIPCIÓN

Esta es una descripción detallada de una función o script. Lo usamos una sola vez en cada tema.

.PARÁMETRO

Esto describe los parámetros en su secuencia de comandos o función. Agregamos una palabra clave .PARAMETER para cada parámetro en nuestros scripts o funciones.

.PARAMETER <Parameter-Name>

Las palabras clave de los parámetros no siguen un orden estricto en el bloque de comentarios. La sintaxis de los parámetros en el script o función determinará el orden en el tema de ayuda.

Puede cambiar el orden cambiando la sintaxis.

Podemos especificar el contenido de la palabra clave del parámetro agregando un comentario, una función o un script. Este comentario debe preceder al nombre de la variable del parámetro.

PowerShell prioriza la descripción asociada con la palabra clave del parámetro sobre el comentario de sintaxis donde se usan ambos.

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

.EJEMPLO

Incluya un comando de muestra que emplee el script o la función. Podemos incluir esta palabra clave para todos los ejemplos en nuestro script o función.

.ENTRADAS

Estos son los objetos .NET que podemos canalizar a nuestro script o función. Podemos agregar una descripción para los objetos de entrada.

.SALIDAS

Estos son los objetos .NET que devuelve nuestro cmdlet. Podemos agregar una descripción para los objetos devueltos.

.NOTAS

Estos son cualquier información adicional sobre el script o la función. La información puede incluir la fecha en que se codifica, el nombre de la función o el nombre del creador.

.ENLACE

Estos son los temas relacionados.

Este es un ejemplo de ayuda basada en comentarios para una función:

En conclusión, podemos agregar ayuda basada en comentarios en funciones o scripts colocándolos en un bloque de comentarios. Al agregar temas de ayuda, use la palabra clave que discutimos anteriormente y recuerde dónde colocar los bloques de comentarios para scripts y funciones.