about_Comment_Based_Help

Artículo
05/25/2021
Tiempo de lectura: 16 minutos

Descripción breve

Describe cómo escribir temas de ayuda basados en comentarios para funciones y scripts.

Descripción larga

Puede escribir temas de ayuda basados en comentarios para funciones y scripts mediante palabras clave de comentario de ayuda especiales.

El cmdlet Get-Help muestra la ayuda basada en comentarios en el mismo formato en el que muestra los temas de ayuda del cmdlet que se generan a partir de archivos XML. Los usuarios pueden usar todos los parámetros de , como Get-Help Detailed, Full, Examples y Online, para mostrar el contenido de la ayuda basada en comentarios.

También puede escribir archivos de ayuda basados en XML para funciones y scripts. Para permitir que el cmdlet encuentre el archivo de ayuda basado en Get-Help XML para una función o script, use la palabra clave .ExternalHelp . Sin esta palabra clave, Get-Help no se pueden encontrar temas de ayuda basados en XML para funciones o scripts.

En este tema se explica cómo escribir temas de ayuda para funciones y scripts. Para obtener información sobre cómo mostrar temas de ayuda para funciones y scripts, vea Get-Help.

Los cmdlets Update-Help y Save-Help solo funcionan en archivos XML. La Ayuda actualizable no admite temas de ayuda basados en comentarios.

Sintaxis de la ayuda basada en comentarios

La sintaxis de la ayuda basada en comentarios es la siguiente:

# .<help keyword>
# <help content>

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

La ayuda basada en comentarios se escribe como una serie de comentarios. Puede escribir un símbolo de comentario antes de cada línea de comentarios, o bien puede usar los # símbolos y para crear un bloque de <# #> comentarios. Todas las líneas del bloque de comentarios se interpretan como comentarios.

Todas las líneas de un tema de ayuda basado en comentarios deben ser contiguas. Si un tema de ayuda basado en comentarios sigue un comentario que no forma parte del tema de ayuda, debe haber al menos una línea en blanco entre la última línea de comentario que no es de ayuda y el principio de la ayuda basada en comentarios.

Las palabras clave definen cada sección de la ayuda basada en comentarios. Cada palabra clave de ayuda basada en comentarios va precedida de un punto . . Las palabras clave pueden aparecer en cualquier orden. Los nombres de palabra clave no distinguen mayúsculas de minúsculas.

Por ejemplo, la .Description palabra clave precede a una descripción de una función o script.

<#
.Description
Get-Function displays the name and syntax of all functions in the session.
#>

El bloque de comentarios debe contener al menos una palabra clave. Algunas de las palabras clave, como .EXAMPLE , pueden aparecer muchas veces en el mismo bloque de comentarios. El contenido de ayuda de cada palabra clave comienza en la línea después de la palabra clave y puede abarcar varias líneas.

Sintaxis de la ayuda basada en comentarios en funciones

La ayuda basada en comentarios de una función puede aparecer en una de estas tres ubicaciones:

Al principio del cuerpo de la función.
Al final del cuerpo de la función.
Antes de la function palabra clave . No puede haber más de una línea en blanco entre la última línea de la ayuda de la función y la palabra function clave .

Por ejemplo:

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

  # function logic
}

function Get-Function
{
   # function logic

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

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

Sintaxis de la ayuda basada en comentarios en scripts

La ayuda basada en comentarios de un script puede aparecer en una de las dos ubicaciones siguientes del script.

Al principio del archivo de script. La ayuda del script solo puede ir precedida de comentarios y líneas en blanco en el script.

Si el primer elemento del cuerpo del script (después de la ayuda) es una declaración de función, debe haber al menos dos líneas en blanco entre el final de la ayuda del script y la declaración de función. De lo contrario, la ayuda se interpreta como ayuda para la función, no como ayuda para el script.
Al final del archivo de script. Sin embargo, si el script está firmado, coloque la ayuda basada en comentarios al principio del archivo de script. El final del script está ocupado por el bloque de firma.

Por ejemplo:

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


function Get-Function { }

function Get-Function { }

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

Sintaxis de la ayuda basada en comentarios en módulos de script

En un módulo de script .psm1 , la ayuda basada en comentarios usa la sintaxis de las funciones, no la sintaxis de los scripts. No puede usar la sintaxis de script para proporcionar ayuda para todas las funciones definidas en un módulo de script.

Por ejemplo, si usa la palabra clave para identificar los archivos de ayuda basados en XML para las funciones de un módulo de script, debe agregar un comentario .ExternalHelp a .ExternalHelp cada función.

# .ExternalHelp <XML-file-name>
function <function-name>
{
  ...
}

Palabras clave de ayuda basadas en comentarios

Las siguientes son palabras clave de ayuda válidas basadas en comentarios. Se muestran en el orden en que suelen aparecer en un tema de ayuda junto con su uso previsto. Estas palabras clave pueden aparecer en cualquier orden en la ayuda basada en comentarios y no distinguen mayúsculas de minúsculas.

. Sinopsis

Breve descripción de la función o script. Esta palabra clave solo se puede usar una vez en cada tema.

. Descripción

Descripción detallada de la función o el script. Esta palabra clave solo se puede usar una vez en cada tema.

. Parámetro

Descripción de un parámetro. Agregue una palabra .PARAMETER clave para cada parámetro en la sintaxis de función o script.

Escriba el nombre del parámetro en la misma línea que la palabra .PARAMETER clave . Escriba la descripción del parámetro en las líneas siguientes a la palabra .PARAMETER clave . Windows PowerShell interpreta todo el texto entre la línea y la palabra clave next o el final del bloque de comentarios .PARAMETER como parte de la descripción del parámetro. La descripción puede incluir saltos de párrafo.

.PARAMETER  <Parameter-Name>

Las palabras clave Parameter pueden aparecer en cualquier orden en el bloque comment, pero la sintaxis de función o script determina el orden en que los parámetros (y sus descripciones) aparecen en el tema de ayuda. Para cambiar el orden, cambie la sintaxis.

También puede especificar una descripción de parámetro colocando un comentario en la sintaxis de función o script inmediatamente antes del nombre de la variable de parámetro. Para que esto funcione, también debe tener un bloque de comentarios con al menos una palabra clave.

Si usa un comentario de sintaxis y una palabra clave, se usa la descripción asociada a la palabra clave y se omite el .PARAMETER .PARAMETER comentario de sintaxis.

<#
.SYNOPSIS
    Short description here
#>
function Verb-Noun {
    [CmdletBinding()]
    param (
        # This is the same as .Parameter
        [string]$Computername
    )
    # Verb the Noun on the computer
}

. Ejemplo

Un comando de ejemplo que usa la función o el script, seguido opcionalmente de una salida de ejemplo y una descripción. Repita esta palabra clave para cada ejemplo.

. Entradas

Los tipos de objetos .NET que se pueden canalizar a la función o script. También puede incluir una descripción de los objetos de entrada.

. Salidas

Tipo .NET de los objetos que devuelve el cmdlet. También puede incluir una descripción de los objetos devueltos.

. Notas

Información adicional sobre la función o el script.

. Enlace

Nombre de un tema relacionado. El valor aparece en la línea debajo de ". Palabra clave LINK" y debe ir precedida de un símbolo de # comentario o incluirse en el bloque de comentarios.

Repita la .LINK palabra clave para cada tema relacionado.

Este contenido aparece en la sección Vínculos relacionados del tema de ayuda.

El .Link contenido de la palabra clave también puede incluir un identificador uniforme de recursos (URI) en una versión en línea del mismo tema de ayuda. La versión en línea se abre cuando se usa el parámetro Online de Get-Help . El URI debe comenzar por "http" o "https".

. Componente

Nombre de la tecnología o característica que usa la función o script, o con la que está relacionada. El parámetro Component de utiliza este valor para filtrar los Get-Help resultados de búsqueda devueltos por Get-Help .

. Papel

Nombre del rol de usuario para el tema de ayuda. El parámetro Role de utiliza este valor para filtrar los Get-Help resultados de búsqueda devueltos por Get-Help .

. Funcionalidad

Palabras clave que describen el uso previsto de la función. El parámetro Functionality de usa este valor para filtrar los Get-Help resultados de búsqueda devueltos por Get-Help .

. FORWARDHELPTARGETNAME

Redirige al tema de ayuda del comando especificado. Puede redirigir a los usuarios a cualquier tema de ayuda, incluidos los temas de ayuda para una función, un script, un cmdlet o un proveedor.

# .FORWARDHELPTARGETNAME <Command-Name>

. FORWARDHELPCATEGORY

Especifica la categoría de ayuda del elemento en .ForwardHelpTargetName . Los valores válidos Alias son , , , , , , , Cmdlet , , HelpFile , o Function Provider General FAQ Glossary ScriptCommand ExternalScript Filter All . Use esta palabra clave para evitar conflictos cuando haya comandos con el mismo nombre.

# .FORWARDHELPCATEGORY <Category>

. REMOTEHELPRUNSPACE

Especifica una sesión que contiene el tema de ayuda. Escriba una variable que contenga un objeto PSSession. El cmdlet Export-PSSession usa esta palabra clave para buscar los temas de ayuda de los comandos exportados.

# .REMOTEHELPRUNSPACE <PSSession-variable>

. EXTERNALHELP

Especifica un archivo de ayuda basado en XML para el script o la función.

# .EXTERNALHELP <XML Help File>

La .ExternalHelp palabra clave es necesaria cuando una función o script se documenta en archivos XML. Sin esta palabra clave, Get-Help no puede encontrar el archivo de ayuda basado en XML para la función o el script.

La .ExternalHelp palabra clave tiene prioridad sobre otras palabras clave de ayuda basadas en comentarios. Si está presente, no muestra ayuda basada en comentarios, incluso si no encuentra un tema de ayuda que coincida con el .ExternalHelp valor de la palabra clave Get-Help .ExternalHelp .

Si un módulo exporta la función, establezca el valor de la palabra .ExternalHelp clave en un nombre de archivo sin una ruta de acceso. Get-Help busca el nombre de archivo especificado en un subdirectorio específico del idioma del directorio del módulo. No hay ningún requisito para el nombre del archivo de ayuda basado en XML para una función, pero un procedimiento recomendado es usar el formato siguiente:

<ScriptModule.psm1>-help.xml

Si la función no se incluye en un módulo, incluya una ruta de acceso al archivo de ayuda basado en XML. Si el valor incluye una ruta de acceso y la ruta de acceso contiene subdirectorios específicos de la referencia cultural de la interfaz de usuario, busca de forma recursiva en los subdirectorios un archivo XML con el nombre del script o la función de acuerdo con los estándares de reserva de lenguaje establecidos para Windows, tal como lo hace en un directorio Get-Help de módulos.

Para obtener más información sobre el formato de archivo de ayuda basado en XML de la ayuda de cmdlets, vea How to Write Cmdlet Help.

Contenido generado automáticamente

El cmdlet genera automáticamente el nombre, la sintaxis, la lista de parámetros, la tabla de atributos de parámetros, los parámetros comunes y los Get-Help comentarios.

Nombre

La sección Nombre de un tema de ayuda de función se toma del nombre de la función en la sintaxis de la función. El nombre de un tema de ayuda de script se toma del nombre de archivo del script. Para cambiar el nombre o su uso de mayúsculas, cambie la sintaxis de la función o el nombre de archivo del script.

Syntax

La sección Sintaxis del tema de ayuda se genera a partir de la sintaxis de función o script. Para agregar detalles a la sintaxis del tema de ayuda, como el tipo .NET de un parámetro, agregue los detalles a la sintaxis. Si no especifica un tipo de parámetro, el tipo object se inserta como valor predeterminado.

Lista de parámetros

La lista de parámetros del tema de ayuda se genera a partir de la sintaxis de función o script y de las descripciones que se agregan mediante la palabra .Parameter clave . Los parámetros de función aparecen en la sección Parámetros del tema de ayuda en el mismo orden en que aparecen en la sintaxis de función o script. La ortografía y el uso de mayúsculas y mayúsculas de los nombres de parámetro también se toman de la sintaxis. No se ve afectado por el nombre del parámetro especificado por la palabra .Parameter clave .

Parámetros comunes

Los parámetros Comunes se agregan a la sintaxis y la lista de parámetros del tema de ayuda, aunque no tengan ningún efecto. Para obtener más información sobre los parámetros comunes, vea about_CommonParameters.

Tabla de atributos de parámetro

Get-Help genera la tabla de atributos de parámetro que aparece cuando se usa el parámetro Full o Parameter de Get-Help . El valor de los atributos Required, Position y Default value se toma de la sintaxis de función o script.

Los valores predeterminados y un valor para Accept Wildcard characters (Aceptar caracteres comodín) no aparecen en la tabla de atributos de parámetro aunque se definan en la función o el script. Para ayudar a los usuarios, proporcione esta información en la descripción del parámetro.

Comentarios

La sección Comentarios del tema de ayuda se genera automáticamente a partir de la función o el nombre del script. No puede cambiar ni afectar a su contenido.

Ejemplos

Ayuda basada en comentarios para una función

La siguiente función de ejemplo incluye ayuda basada en comentarios:

function Add-Extension
{
param ([string]$Name,[string]$Extension = "txt")
$name = $name + "." + $extension
$name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name.
Takes any strings for the file name or extension.

.PARAMETER Name
Specifies the file name.

.PARAMETER Extension
Specifies the extension. "Txt" is the default.

.INPUTS

None. You cannot pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension
or file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Los resultados son los siguientes:

Get-Help -Name "Add-Extension" -Full

NAME

Add-Extension

SYNOPSIS

Adds a file name extension to a supplied name.

SYNTAX

Add-Extension [[-Name] <String>] [[-Extension] <String>]
[<CommonParameters>]

DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

PARAMETERS

-Name
Specifies the file name.

Required?                    false
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-Extension
Specifies the extension. "Txt" is the default.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type
"get-help about_commonparameters".

INPUTS
None. You cannot pipe objects to Add-Extension.

OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

Example 1

PS> extension -name "File"
File.txt

Example 2

PS> extension -name "File" -extension "doc"
File.doc

Example 3

PS> extension "File" "doc"
File.doc

RELATED LINKS

http://www.fabrikam.com/extension.html
Set-Item

Descripciones de parámetros en la sintaxis de función

Este ejemplo es el mismo que el anterior, salvo que las descripciones de parámetros se insertan en la sintaxis de la función. Este formato es muy útil cuando las descripciones son breves.

function Add-Extension
{
param
(

[string]
#Specifies the file name.
$name,

[string]
#Specifies the file name extension. "Txt" is the default.
$extension = "txt"
)

$name = $name + "." + $extension
$name

<#
.SYNOPSIS

Adds a file name extension to a supplied name.

.DESCRIPTION

Adds a file name extension to a supplied name. Takes any strings for the
file name or extension.

.INPUTS

None. You cannot pipe objects to Add-Extension.

.OUTPUTS

System.String. Add-Extension returns a string with the extension or
file name.

.EXAMPLE

PS> extension -name "File"
File.txt

.EXAMPLE

PS> extension -name "File" -extension "doc"
File.doc

.EXAMPLE

PS> extension "File" "doc"
File.doc

.LINK

http://www.fabrikam.com/extension.html

.LINK

Set-Item
#>
}

Ayuda basada en comentarios para un script

El siguiente script de ejemplo incluye ayuda basada en comentarios. Observe las líneas en blanco entre el cierre #> y la Param instrucción . En un script que no tiene una instrucción , debe haber al menos dos líneas en blanco entre el comentario final del tema de ayuda y la Param primera declaración de función. Sin estas líneas en blanco, Get-Help asocia el tema de ayuda a la función, no al script.

<#
.SYNOPSIS

Performs monthly data updates.

.DESCRIPTION

The Update-Month.ps1 script updates the registry with new data generated
during the past month and generates a report.

.PARAMETER InputPath
Specifies the path to the CSV-based input file.

.PARAMETER OutputPath
Specifies the name and path for the CSV-based output file. By default,
MonthlyUpdates.ps1 generates a name from the date and time it runs, and
saves the output in the local directory.

.INPUTS

None. You cannot pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 does not generate any output.

.EXAMPLE

PS> .\Update-Month.ps1

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

.EXAMPLE

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath `
C:\Reports\2009\January.csv
#>

param ([string]$InputPath, [string]$OutPutPath)

function Get-Data { }
...

El comando siguiente obtiene la ayuda del script. Dado que el script no está en un directorio que aparece en la variable de entorno, el comando que obtiene la ayuda $env:Path del script debe especificar la ruta de acceso del Get-Help script.

Get-Help -Path .\update-month.ps1 -Full

# NAME

C:\ps-test\Update-Month.ps1

# SYNOPSIS

Performs monthly data updates.

# SYNTAX

C:\ps-test\Update-Month.ps1 [-InputPath] <String> [[-OutputPath]
<String>] [<CommonParameters>]

# DESCRIPTION

The Update-Month.ps1 script updates the registry with new data
generated during the past month and generates a report.

# PARAMETERS

-InputPath
Specifies the path to the CSV-based input file.

Required?                    true
Position?                    0
Default value
Accept pipeline input?       false
Accept wildcard characters?

-OutputPath
Specifies the name and path for the CSV-based output file. By
default, MonthlyUpdates.ps1 generates a name from the date
and time it runs, and saves the output in the local directory.

Required?                    false
Position?                    1
Default value
Accept pipeline input?       false
Accept wildcard characters?

<CommonParameters>
This cmdlet supports the common parameters: -Verbose, -Debug,
-ErrorAction, -ErrorVariable, -WarningAction, -WarningVariable,
-OutBuffer and -OutVariable. For more information, type,
"get-help about_commonparameters".

# INPUTS

None. You cannot pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 does not generate any output.

Example 1

PS> .\Update-Month.ps1

Example 2

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv

Example 3

PS> .\Update-Month.ps1 -inputpath C:\Data\January.csv -outputPath
C:\Reports\2009\January.csv

# RELATED LINKS

Redirigir a un archivo XML

Puede escribir temas de ayuda basados en XML para funciones y scripts. Aunque la ayuda basada en comentarios es más fácil de implementar, la ayuda basada en XML es necesaria para la Ayuda actualizable y para proporcionar temas de ayuda en varios idiomas.

En el ejemplo siguiente se muestran las primeras líneas del Update-Month.ps1 script. El script usa la palabra clave para especificar la ruta de acceso a un tema de ayuda basado .ExternalHelp en XML para el script.

Tenga en cuenta que el valor de la .ExternalHelp palabra clave aparece en la misma línea que la palabra clave . Cualquier otra ubicación es ineficaz.

# .ExternalHelp C:\MyScripts\Update-Month-Help.xml

param ([string]$InputPath, [string]$OutPutPath)
function Get-Data { }
...

En los ejemplos siguientes se muestran tres colocaciones válidas de la .ExternalHelp palabra clave en una función.

function Add-Extension
{
# .ExternalHelp C:\ps-test\Add-Extension.xml

param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}

function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name

# .ExternalHelp C:\ps-test\Add-Extension.xml
}

# .ExternalHelp C:\ps-test\Add-Extension.xml
function Add-Extension
{
param ([string] $name, [string]$extension = "txt")
$name = $name + "." + $extension
$name
}

Redirigir a un tema de Ayuda diferente

El código siguiente es un extracto del principio de la función de ayuda integrada en PowerShell, que muestra una pantalla de texto de ayuda a la vez. Dado que el tema de ayuda del cmdlet describe la función de ayuda, la función de ayuda usa las palabras clave y para redirigir al usuario al Get-Help tema de ayuda del .ForwardHelpTargetName .ForwardHelpCategory Get-Help cmdlet.

function help
{

<#
.FORWARDHELPTARGETNAME Get-Help
.FORWARDHELPCATEGORY Cmdlet
#>
[CmdletBinding(DefaultParameterSetName='AllUsersView')]
param(
[Parameter(Position=0, ValueFromPipelineByPropertyName=$true)]
[System.String]
${Name},
...

El comando siguiente usa esta característica:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

Consulte también

about_Functions

about_Functions_Advanced_Parameters

about_Scripts

Escritura de la Ayuda de cmdlets

about_Comment_Based_Help

Valore su experiencia

Descripción breve

Descripción larga

Sintaxis de la ayuda basada en comentarios

Sintaxis de la ayuda basada en comentarios en funciones

Sintaxis de la ayuda basada en comentarios en scripts

Sintaxis de la ayuda basada en comentarios en módulos de script

Palabras clave de ayuda basadas en comentarios

. Sinopsis

. Descripción

. Parámetro

. Ejemplo

. Entradas

. Salidas

. Notas

. Enlace

. Componente

. Papel

. Funcionalidad

. FORWARDHELPTARGETNAME

. FORWARDHELPCATEGORY

. REMOTEHELPRUNSPACE

. EXTERNALHELP

Contenido generado automáticamente

Nombre

Syntax

Lista de parámetros

Parámetros comunes

Tabla de atributos de parámetro

Comentarios

Ejemplos

Ayuda basada en comentarios para una función

Descripciones de parámetros en la sintaxis de función

Ayuda basada en comentarios para un script

Redirigir a un archivo XML

Redirigir a un tema de Ayuda diferente

Consulte también

Comentarios