PowerShell Logo

Cómo documentar nuestros scripts de PowerShell

A la hora de documentar nuestros scripts o nuestras funciones de PowerShell es necesario que conozcamos la estructura esperada para que el comando Get-Help o el propio Host pueda extraer la información.

La estructura es bastante sencilla, se basa en una palabra clave de ayuda, SYNOPSIS, DESCRIPTION o EXAMPLE, precedida de un punto. Tras ello, un comentario asociado a dicha palabra clave que empezará en la siguiente línea. Dicha estructura debe de ir dentro de un comentario de bloque o precedida por el símbolo # en cada línea. A continuación se muestra cómo sería en ambos casos

# .[palabra clave de ayuda]
# [contenido de la ayuda relacionado con la palabra clave]
 
<#
 .[palabra clave de ayuda]
 [contenido de la ayuda relacionado con la palabra clave]
#>

El bloque de documentación puede aparecer al principio del cuerpo de la función, al final de la función o anteriormente a la palabra clave reservada function. En el caso de los scripts, ésta puede situarse al principio del fichero precedida únicamente por otros comentarios o líneas en blanco o al final del mismo salvo si es un script firmado. Un detalle importante, si el primer miembro del script es una función será necesario dejar dos líneas en blanco para evitar que sea interpretada como la documentación de la función.

Documentación autogenerada por PowerShell

Por defecto, existe un conjunto de datos que por defecto PowerShell muestra y genera de forma automática cuando llamamos al comando Get-Help. Lo más importantes son los siguientes:

  • Name : Obtenido a partir del nombre del fichero de nuestro script o del nombre de la función.
  • Syntax : Extraído de la firma de nuestro script o función.
  • Parameter List : En esta ocasión, si incluímos detalles sobre los parámetros con lo que explicaremos a continuación, la información se extraerá de ahí. Si no, a partir de la firma de nuestro script o función.

Palabras clave que podemos utilizar

Junto con lo anterior, tenemos una colección de otros parámetros que podemos añadir a nuestra documentación para hacerla más completa.

  • SYNOPSIS : una pequea descripción de la función o el script. Esta palabra sólo se puede incluir una vez.
  • DESCRIPTION : Una extensión del parámetro anterior para describir de forma detallada qué realiza la función o el script. Esta palabra sólo se puede incluir una vez.
  • PARAMETER : La descripción de cada uno de los parámetros que nuestra función o script. Es necesario incluir esta palabra clave por cada parámetro que utilicemos. El orden que utilicemos para ponerlos será el orden en el que aparezcan en la ayuda de PowerShell.
  • EXAMPLE : Diferentes ejemmplos para para ayudar al usuario a utilizar nuestra función o script. Podemos añadir tantos ejemplos como deseemos./li>
  • INPUTS : Si vamos a usar este comando en una tubería, con esta palabra clave definiremos el tipo de objeto del .Net Framework que acepta en su entrada.
  • OUTPUTS : Similar al caso anterior pero sobre el tipo de objeto de .Net Framework que devolverá al finalizar su ejecucción.
  • NOTES : Información adicional que queramos añadir sobre nuestro script o función.

No son los únicos pero sí los que probablemente utilicemos más a menudo. Si tenemos curiosidad sobre qué otros parámetros podemos utilizar podemos consultar el artículo de la documentación asociado a este tema. Para ello, desde una consola lanzaremos lo siguiente:

Get-Help about_Comment_Based_Help

O directamente en la referencia de TechNet de forma online.

Un ejemplo de ello lo podéis ver en el script que publiqué para aprovisionar nuestras imágenes de Windows Nano Server.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.