acerca de la ayuda basada en comentarios

Breve descripción

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 utilizando palabras clave de comentarios de ayuda especiales.

El cmdlet Get-Help muestra 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 utilizar todos los parámetros de Get-Help, como Detallado, Completo, Ejemplos y En línea, 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 Get-Help busque el archivo de ayuda basado en XML para una función o secuencia de comandos, utilice la palabra clave .ExternalHelp. Sin esta palabra clave, Get-Help no puede encontrar temas de ayuda basados en XML para funciones o scripts.

Este tema 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, consulte Obtener ayuda.

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

Sintaxis para 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 puede usar los símbolos <# y #> para crear un bloque de comentarios. . Todas las líneas dentro 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 a 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 sea de ayuda y el comienzo de la ayuda basada en comentarios.

Las palabras clave definen cada sección de ayuda basada en comentarios. Cada palabra clave de ayuda basada en comentarios está precedida por un punto .. Las palabras clave pueden aparecer en cualquier orden. Los nombres de las palabras clave no distinguen entre mayúsculas y minúsculas.

Por ejemplo, la palabra clave .Description 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 para cada palabra clave comienza en la línea después de la palabra clave y puede abarcar varias líneas.

Sintaxis para ayuda basada en comentarios en funciones

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

Al comienzo del cuerpo de la función.
Al final del cuerpo de la función.
Antes de la palabra clave function. 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 clave function.

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 para ayuda basada en comentarios en scripts

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

Al principio del archivo de script. La ayuda del script sólo puede ir precedida de comentarios y líneas en blanco.
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 del script. El final del guión lo ocupa el bloque de firma.

Por ejemplo:

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


function Get-Function { }

function Get-Function { }

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

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

En un módulo de secuencia de comandos .psm1, la ayuda basada en comentarios utiliza la sintaxis de las funciones, no la sintaxis de las secuencias de comandos. No puede utilizar la sintaxis de secuencia de comandos para proporcionar ayuda para todas las funciones definidas en un módulo de secuencia de comandos.

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

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

Palabras clave de ayuda basadas en comentarios

Las siguientes son palabras clave válidas de ayuda basadas en comentarios. Se enumeran 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 entre mayúsculas y minúsculas.

.SINOPSIS

Una breve descripción de la función o script. Esta palabra clave se puede utilizar sólo una vez en cada tema.

.DESCRIPCIÓN

Una descripción detallada de la función o script. Esta palabra clave se puede utilizar sólo una vez en cada tema.

.PARÁMETRO

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

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

.PARAMETER  <Parameter-Name>

Las palabras clave de parámetros pueden aparecer en cualquier orden en el bloque de comentarios, pero la sintaxis de la función o del script determina el orden en el que aparecen los parámetros (y sus descripciones) 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 la función o del script inmediatamente antes del nombre de la variable del parámetro. Para que esto funcione, también debes tener un bloque de comentarios con al menos una palabra clave.

Si utiliza un comentario de sintaxis y una palabra clave .PARAMETER, se utiliza la descripción asociada con la palabra clave .PARAMETER y se ignora el 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 muestra que utiliza la función o secuencia de comandos, seguido opcionalmente de un resultado de muestra y una descripción. Repita esta palabra clave para cada ejemplo.

.ENTRADA

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

El 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 script.

.ENLACE

El nombre de un tema relacionado. El valor aparece en la línea debajo de la palabra clave ".LINK" y debe estar precedido por un símbolo de comentario # o incluido en el bloque de comentarios.

Repita la palabra clave .LINK para cada tema relacionado.

Este contenido aparece en la sección Enlaces relacionados del tema de ayuda.

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

.COMPONENTE

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

.ROLE

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

.FUNCIONALIDAD

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

.FORWARDHELPTARGETNAME

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

# .FORWARDHELPTARGETNAME <Command-Name>

.FORWARDHELPCATEGORIA

Especifica la categoría de ayuda del elemento en .ForwardHelpTargetName. Los valores válidos son Alias, Cmdlet, HelpFile, Función, Proveedor, General, Preguntas frecuentes, Glosario, ScriptCommand, ExternalScript, Filtro, o Todos. Utilice 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. Introduzca una variable que contenga un objeto PSSession. El cmdlet Export-PSSession utiliza esta palabra clave para buscar los temas de ayuda para los comandos exportados.

# .REMOTEHELPRUNSPACE <PSSession-variable>

.AYUDA EXTERNA

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

# .EXTERNALHELP <XML Help File>

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

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

Si la función se exporta mediante un módulo, establezca el valor de la palabra clave .ExternalHelp en un nombre de archivo sin ruta. Get-Help busca el nombre de archivo especificado en un subdirectorio específico del idioma del directorio del módulo. No existen requisitos para el nombre del archivo de ayuda basado en XML para una función, pero una práctica recomendada es utilizar el siguiente formato:

<ScriptModule.psm1>-help.xml

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

Para obtener más información sobre el formato de archivo de ayuda basado en XML de ayuda de cmdlet, consulte Cómo escribir ayuda de cmdlet.

Contenido generado automáticamente

El cmdlet Get-Help 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 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 del script se toma del nombre del archivo del script. Para cambiar el nombre o sus mayúsculas, cambie la sintaxis de la función o el nombre del archivo del script.

Sintaxis

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

Lista de parámetros

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

Parámetros comunes

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

Tabla de atributos de parámetros

Get-Help genera la tabla de atributos de parámetros que aparece cuando se utiliza el parámetro Full o Parameter de Get-Help. El valor de los atributos de valor Requerido, Posición y Predeterminado se toma de la sintaxis de la función o del script.

Los valores predeterminados y un valor para Aceptar caracteres comodín no aparecen en la tabla de atributos de parámetros incluso cuando están definidos en la función o secuencia de comandos. Para ayudar a los usuarios, proporcione esta información en la descripción del parámetro.

Observaciones

La sección Observaciones del tema de ayuda se genera automáticamente a partir del nombre de la función o script. No puede cambiar ni afectar 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 funciones

Este ejemplo es igual que el anterior, excepto que las descripciones de los parámetros se insertan en la sintaxis de la función. Este formato es más ú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 la instrucción #> de cierre y la instrucción Param. En un script que no tiene una declaración Param, debe haber al menos dos líneas en blanco entre el comentario final en el tema de ayuda y la primera declaración de función. Sin estas líneas en blanco, Get-Help asocia el tema de ayuda con la función, no con el 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 siguiente comando obtiene la ayuda del script. Debido a que el script no está en un directorio que aparezca en la variable de entorno $env:Path, el comando Get-Help que obtiene la ayuda del script debe especificar la ruta del script.

Get-Help -Name .\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, se requiere ayuda basada en XML para la Ayuda actualizable y para proporcionar temas de ayuda en varios idiomas.

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

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

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

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

Los siguientes ejemplos muestran tres ubicaciones válidas de la palabra clave .ExternalHelp 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 siguiente código es un extracto del comienzo 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 para el cmdlet Get-Help describe la función de ayuda, la función de ayuda utiliza las palabras clave .ForwardHelpTargetName y .ForwardHelpCategory para redirigir el usuario al tema de ayuda del cmdlet Get-Help.

function help
{

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

El siguiente comando utiliza esta característica:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

Ver también

acerca de_Funciones
about_Functions_Advanced_Parameters
acerca de_Scripts
Cómo escribir ayuda de cmdlet