Compartir a través de

acerca_de_Ayuda_Basada_en_Comentarios

Descripción breve

Describe cómo escribir contenido de ayuda basado en comentarios para funciones y scripts.

Descripción larga

Puede escribir contenido de ayuda basado 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 el contenido de ayuda del cmdlet que se genera a partir de archivos XML. Los usuarios pueden usar 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 habilitar el cmdlet Get-Help para buscar el archivo de ayuda basado en XML de una función o script, use la palabra clave .EXTERNALHELP. Sin esta palabra clave, Get-Help no puede encontrar contenido de ayuda basado en XML para funciones o scripts.

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

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

Sintaxis para la ayuda basada en comentarios

Para crear contenido de ayuda basado en comentarios, puede usar cualquier estilo de comentarios: comentarios de una sola línea o bloquear comentarios.

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

# .<help keyword>
# <help content>

o

<#
    .<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 de <# 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 comentarios que no sea de ayuda y el principio 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 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 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 de cada palabra clave comienza en la línea después de la palabra clave y puede abarcar varias líneas.

Sintaxis para la ayuda basada en comentarios en funciones

La ayuda basada en comentarios para 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 palabra clave function. No puede haber más de una línea en blanco entre la última línea de la ayuda de función y la palabra clave function.

Por ejemplo:

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

    # function logic
}

o

function Get-Function {
    # function logic

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

o

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

Sintaxis para 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.

    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 { }

o

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

Palabras clave de ayuda basadas en comentarios

A continuación se muestran palabras clave de ayuda basadas en comentarios válidas. Estas palabras clave pueden aparecer en cualquier orden en la ayuda basada en comentarios y no distinguen mayúsculas de minúsculas. Las palabras clave se enumeran en este artículo en el orden en que normalmente aparecen en un tema de ayuda.

.SYNOPSIS

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

.DESCRIPTION

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

.PARAMETER

Descripción de un parámetro. Agregue una palabra clave .PARAMETER para cada parámetro de la sintaxis de 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 palabra clave siguiente 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 función o script determina el orden en el que aparecen los parámetros (y sus descripciones) en el tópico 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 .PARAMETER, se usa la descripción asociada a la palabra clave .PARAMETER y se omite 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
}

.EXAMPLE

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

.INPUTS

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. Repita esta palabra clave para cada tipo de entrada.

.OUTPUTS

Tipo de .NET de los objetos que devuelve el cmdlet. También puede incluir una descripción de los objetos devueltos. Repita esta palabra clave para cada tipo de salida.

.NOTES

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

Nombre de un tema relacionado. Repita esta palabra clave para cada tema relacionado. Este contenido aparece en la sección Vínculos relacionados del tema de Ayuda.

El contenido de la palabra clave .LINK 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 utiliza el parámetro En línea de Get-Help. El URI debe comenzar por http o https.

.COMPONENT

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

.ROLE

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

.FUNCTIONALITY

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

.FORWARDHELPTARGETNAME <Command-Name>

Redirige al tema de ayuda del comando especificado. Puede redirigir a los usuarios a cualquier tema de ayuda, incluido el contenido de ayuda de 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 son Alias, Cmdlet, HelpFile, Function, Provider, General, FAQ, Glossary, ScriptCommand, ExternalScript, Filtero All. Use esta palabra clave para evitar conflictos cuando haya comandos con el mismo nombre.

# .FORWARDHELPCATEGORY <Category>

.REMOTEHELPRUNSPACE <PSSession-variable>

Especifica una sesión que contiene el tema de ayuda. Escriba una variable que contenga un objeto de PSSession. El cmdlet export-PSSession usa esta palabra clave para buscar el contenido 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 palabra clave .EXTERNALHELP 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 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, aunque no encuentre un tema de ayuda que coincida con el valor de la palabra clave .EXTERNALHELP.

Si un módulo exporta la función, establezca el valor de la palabra clave .EXTERNALHELP en un nombre de archivo sin una ruta de acceso. Get-Help busca el nombre de archivo especificado en un subdirectorio específico del lenguaje del directorio del módulo. No hay ningún requisito para el nombre del archivo de ayuda basado en XML para una función. A partir de PowerShell 5.0, las funciones exportadas por un módulo se pueden documentar en un archivo de ayuda denominado para el módulo. No es necesario usar .EXTERNALHELP la palabra clave comment. Por ejemplo, si el Test-Function módulo exporta la MyModule función, puede asignar un nombre al archivo MyModule-help.xmlde ayuda . El Get-Help cmdlet busca ayuda para la Test-Function función en el MyModule-help.xml archivo del directorio del módulo.

Si la función no está incluida en un módulo, incluya una ruta de acceso 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 recursivamente en los subdirectorios un archivo XML con el nombre del script o función de acuerdo con las normas de retroceso de idioma establecidas para Windows, al igual que hace en un directorio de módulos.

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

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 de script se toma del nombre de archivo del script. Para cambiar el nombre o su mayúscula, cambie la sintaxis de la función o el nombre de archivo del script.

Sintaxis

La sección Syntax 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 de un parámetro .NET, incorpórelos en la sintaxis. Si no especifica un tipo de parámetro, el Tipo de objeto 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 clave .PARAMETER. 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 la función o del script. La ortografía y las mayúsculas de los nombres de los parámetros también se toman de la sintaxis. No se ve afectado por el nombre de parámetro especificado por la palabra clave .PARAMETER.

Parámetros comunes

Los parámetros comunes se agregan a la sintaxis y a la lista de parámetros del tema de ayuda, incluso si no tienen 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ámetros que aparece cuando se utiliza el parámetro Full o Parameter de Get-Help. El valor de los atributos Required, Positiony Default se toma de la sintaxis de la función o script.

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

Observaciones

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

Examples

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 can't pipe objects to Add-Extension.

.OUTPUTS

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

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-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 can't pipe objects to Add-Extension.

OUTPUTS

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

Example 1

PS> Add-Extension -Name "File"
File.txt

Example 2

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

Example 3

PS> Add-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 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 can't pipe objects to Add-Extension.

.OUTPUTS

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

.EXAMPLE

PS> Add-Extension -Name "File"
File.txt

.EXAMPLE

PS> Add-Extension -Name "File" -Extension "doc"
File.doc

.EXAMPLE

PS> Add-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 instrucción param. En un script que no tiene una instrucción param, debe haber al menos dos líneas en blanco entre el comentario final del tema de ayuda y la 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 can't pipe objects to Update-Month.ps1.

.OUTPUTS

None. Update-Month.ps1 doesn't 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. Dado que el script no está en un directorio que aparece en la variable de entorno $Env:PATH, el comando Get-Help que obtiene la ayuda del script debe especificar la ruta de acceso 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 can't pipe objects to Update-Month.ps1.

# OUTPUTS

None. Update-Month.ps1 doesn't 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

Redireccionamiento a un archivo XML

Puede escribir contenido de ayuda basado 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 contenido de ayuda en varios idiomas.

En el ejemplo siguiente se muestran las primeras líneas del script de Update-Month.ps1. El script usa la palabra clave .EXTERNALHELP para especificar la ruta de acceso 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 { }
...

En los ejemplos siguientes se 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
}

Redireccionamiento 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 Get-Help describe la función de ayuda, la función de ayuda usa las palabras clave .FORWARDHELPTARGETNAME y .FORWARDHELPCATEGORY para redirigir al 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 usa esta característica:

Get-Help -Name help

NAME

Get-Help

SYNOPSIS

Displays information about PowerShell cmdlets and concepts.
...

Consulte también

  • Last updated on