about_Comment_Based_Help

Artículo
04/13/2023

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 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 Get-Help cmdlet busque el archivo de ayuda basado en XML para una función o script, use la .ExternalHelp palabra clave . Sin esta palabra clave, Get-Help no puede 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 para 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 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 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 por 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 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 function palabra clave . No puede haber más de una línea en blanco entre la última línea de la ayuda de función y la function palabra 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 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 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 para la ayuda basada en comentarios en módulos de script

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

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

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

Palabras clave de ayuda basadas en comentarios

A continuación se muestran palabras clave de ayuda basadas en comentarios válidas. Se muestran en el orden en que normalmente aparecen 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.

.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 .PARAMETER palabra 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 .PARAMETER palabra clave . Escriba la descripción del parámetro en las líneas que siguen a la .PARAMETER palabra clave . Windows PowerShell interpreta todo el texto entre la .PARAMETER línea 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 Parameter 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 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 .PARAMETER palabra clave, se usa la descripción asociada a la .PARAMETER palabra clave 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.

.OUTPUTS

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

.NOTES

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

.LINK

Nombre de un tema relacionado. El valor aparece en la línea debajo de la palabra clave ".LINK" y debe ir precedido de un símbolo # de comentario o incluido 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".

.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 usa este valor para filtrar los resultados de búsqueda devueltos por 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

Redirige al tema de ayuda del comando especificado. Puede redirigir a los usuarios a cualquier tema de ayuda, incluidos los temas 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, FAQScriptCommandGeneralProviderGlossary, ExternalScript, o . FilterAll 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 se puede encontrar el archivo de ayuda basado en XML para la función o script.

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

Si un módulo exporta la función, establezca el valor de la .ExternalHelp palabra 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 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, pero un procedimiento recomendado es usar el siguiente formato:

<ScriptModule.psm1>-help.xml

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 de acceso y la ruta de acceso contiene subdirectorios específicos de la referencia cultural de la interfaz de usuario, Get-Help busca de forma recursiva los subdirectorios de 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, igual que 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 Cómo escribir ayuda de cmdlets.

Contenido generado automáticamente

El cmdlet genera Get-Help 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 Sintaxis del tema de ayuda se genera a partir de la sintaxis de la función o script. Para agregar detalles a la sintaxis del tema de ayuda, como el tipo de .NET de un parámetro, agregue los detalles a 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 .Parameter palabra 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 mayúsculas de los nombres de parámetro también se toma de la sintaxis . No se ve afectado por el nombre de parámetro especificado por la .Parameter palabra clave .

Parámetros comunes

Los parámetros comunes se agregan a la sintaxis y 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, consulte 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 de valor Required, Position y Default se toma de la sintaxis de 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.

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 se 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:

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 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 el cierre #> y la Param instrucción . En un script que no tiene una Param instrucción , 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 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. Dado que el script no está en un directorio que aparece en la $env:Path variable de entorno, el Get-Help comando 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 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

Redireccionamiento 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 ayuda actualizable y para proporcionar temas de ayuda en varios idiomas.

En el ejemplo siguiente se muestran las primeras líneas del script Update-Month.ps1. El script usa la .ExternalHelp palabra clave 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 .ExternalHelp palabra clave 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 .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
}

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 Get-Help cmdlet describe la función de ayuda, la función de ayuda usa las .ForwardHelpTargetName palabras clave y .ForwardHelpCategory para redirigir al usuario al tema de ayuda del Get-Help cmdlet.

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

Compartir a través de