TEMA
    about_Comment_Based_Help

DESCRIPCIÓN BREVE
    Describe cómo escribir temas de Ayuda basada en comentarios para funciones 
    y scripts.

DESCRIPCIÓN DETALLADA
    Se pueden escribir temas de Ayuda basada en comentarios para 
    funciones y scripts utilizando palabras clave de comentario de 
    Ayuda especiales. 

    El cmdlet Get-Help muestra la Ayuda basada en comentarios en el 
    mismo formato en que muestra los temas de Ayuda de cmdlet que se 
    generan a partir de los archivos XML. Los usuarios pueden 
    utilizar todos los parámetros de Get-Help, tales como Detailed, 
    Full, Example y Online, a fin de mostrar la Ayuda de funciones y scripts.

    También es posible escribir archivos de Ayuda basada en XML para 
    scripts y funciones utilizando palabras clave de comentario de 
    Ayuda, y redirigir a los usuarios a un archivo de Ayuda diferente. 

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


 SINTAXIS DE LA AYUDA BASADA EN COMENTARIOS
    La sintaxis de la Ayuda basada en comentarios es la siguiente:
        # .< palabra clave de ayuda>
        # <contenido de ayuda>
 
    -o bien,

        <#
            .< palabra clave de ayuda>
            < contenido de ayuda>
        #>


    La Ayuda basada en comentarios se escribe como una serie de comentarios. 
    Se puede escribir un símbolo de comentario (#) delante de cada línea de 
    comentarios, o bien utilizar los símbolos "<#" y "#>" para crear un 
    bloque de comentario. Todas las líneas contenidas en el bloque de 
    comentario se interpretan como comentarios.

    Todas las líneas de un tema de Ayuda basada en comentarios deben 
    ser contiguas. Si un tema de Ayuda basada en comentarios está 
    situado justo tras un comentario que no forma parte del tema de 
    Ayuda, debe dejarse por lo 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 va precedida de 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 un script.

        <#
	    .Description
            Get-Function muestra el nombre y la sintaxis de todas las 
            funciones de la sesión.
        #>

    El bloque de comentario debe contener una palabra clave por lo 
    menos. Algunas de las palabras clave, como EXAMPLE, pueden 
    aparecer muchas veces en el mismo bloque de comentario. El 
    contenido de Ayuda correspondiente a cada palabra clave comienza 
    en la línea que figura después de la palabra clave y puede 
    abarcar varias líneas. 



 SINTAXIS DE LA AYUDA BASADA EN COMENTARIOS EN LAS FUNCIONES

    La Ayuda basada en comentarios de una función puede aparecer en 
    una de las tres ubicaciones siguientes:

        -- 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 última línea de la Ayuda la de 
           función y la palabra clave Function. 

 

    Por ejemplo:

        function MiFunción 
        {
            <#
            .< palabra clave de ayuda>
            < contenido de ayuda>
            #>

            <comandos de función>
        }


    -o bien,

        function MiFunción 
        {
            <comandos de función>

            <#
            .< palabra clave de ayuda>
            < contenido de ayuda>
            #>
        }

    -o bien,

        <#
        .< palabra clave de ayuda>
        < contenido de ayuda>
        #>
        function MiFunción { }



 SINTAXIS DE LA AYUDA BASADA EN COMENTARIOS EN LOS SCRIPTS

    La Ayuda basada en comentarios de un script puede aparecer en una 
    de las dos ubicaciones siguientes en el script.

    -- Al principio del archivo de script. La Ayuda del script 
       solamente puede ir precedida en el script por 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 por lo menos 
       dos líneas en blanco entre el fin de la Ayuda del script y la 
       declaración de función. De lo contrario, la Ayuda se 
       interpretará como si correspondiese a la función y no al script.

    -- Al final del archivo de script.



    Por ejemplo:

        <#
        .< palabra clave de ayuda>
        < contenido de ayuda>
        #>


        function MiFunción { }

    -o bien,


        function MiFunción { }

        <#
        .< palabra clave de ayuda>
        < contenido de ayuda>
        #>



 PALABRAS CLAVE DE LA AYUDA BASADA EN COMENTARIOS
    A continuación se enumeran las palabras clave válidas de Ayuda 
    basada en comentarios, 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.


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

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

    .PARAMETER <Nombre-del-parámetro>
        Descripción de un parámetro. Se puede incluir una palabra 
        clave Parameter por cada parámetro que haya en la sintaxis de 
        la función o el script.

        Las palabras clave Parameter pueden aparecer en cualquier 
        orden dentro el bloque de comentario; sin embargo, la sintaxis 
        de la función o el script determina en qué orden aparecerán los 
        parámetros (y sus descripciones respectivas) en el tema de Ayuda. 
        Para cambiar el orden, deberá cambiar la sintaxis.
 
        También se puede especificar la descripción de un parámetro 
        incluyendo un comentario en la sintaxis de la función o del 
        script inmediatamente antes del nombre de variable del parámetro.
        Si utiliza un comentario de sintaxis y una palabra clave 
        Parameter, se utilizará la descripción asociada a la palabra 
        clave Parameter y se omitirá el comentario de sintaxis.

    .EXAMPLE
        Comando de ejemplo que utiliza la función o el script, y que 
        puede ir seguido, opcionalmente, por un ejemplo de resultado 
        y una descripción. Repita esta palabra clave por cada ejemplo.

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

    .OUTPUTS
        El tipo de .NET Framework de los objetos que el cmdlet devuelve. 
        También se 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. Repita esta palabra clave por 
        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)a una versión en pantalla 
        del mismo tema de Ayuda. La versión en pantalla se abre cuando se 
        utiliza el parámetro Online de Get-Help. El identificador URI debe 
        comenzar con "http" o "https".

    .COMPONENT
        Tecnología o característica que la función o el script utiliza, 
        o con la que está relacionado. Este contenido aparece cuando el 
        comando Get-Help incluye el parámetro Component de Get-Help.

    .ROLE
        Rol de usuario correspondiente al tema de Ayuda. Este 
        contenido aparece cuando el comando Get-Help incluye el 
        parámetro Role de Get-Help.

    .FUNCTIONALITY
        Uso previsto de la función. Este contenido aparece cuando el 
        comando Get-Help incluye el parámetro Functionality de Get-Help.

    .FORWARDHELPTARGETNAME <Nombre-del-comando>
        Redirige al usuario al tema de Ayuda del comando especificado. 
        Es posible redirigir a los usuarios a cualquier tema de Ayuda, 
        incluso a los correspondientes a una función, un script, 
        un cmdlet o un proveedor. 

    .FORWARDHELPCATEGORY <Categoría>
        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, Filter o All. 
        Utilice esta palabra clave para evitar conflictos cuando existan 
        comandos con el mismo nombre.

    .REMOTEHELPRUNSPACE <variable-PSSession>
        Especifica una sesión que contiene el tema de Ayuda. Escriba 
        una variable que contenga una sesión PSSession. El cmdlet 
        Export-PSSession utiliza esta palabra clave para buscar los 
        temas de Ayuda correspondientes a los comandos exportados.

    .EXTERNALHELP <Ruta de acceso del archivo de Ayuda XML>
        Especifica la ruta de acceso a un archivo de Ayuda basada en 
        XML correspondiente a un script o una función. 

        En Windows Vista y en las versiones de Windows posteriores, 
        si la ruta especificada contiene subdirectorios específicos 
        de la referencia cultural de la interfaz de usuario, Get-Help 
        busca de forma recursiva en todos ellos hasta encontrar un 
        archivo XML con el nombre del script o la función, de acuerdo 
        con las normas de reserva de idioma establecidas para Windows 
        Vista, exactamente igual que hace con todos los temas de 
        Ayuda basados en XML. 

        Para obtener más información sobre el formato de los archivos de Ayuda 
        basada en XML para los cmdlet, vea el tema acerca de cómo crear Ayuda 
        de cmdlets en MSDN Library (Microsoft Developer Network)en 
        https://go.microsoft.com/fwlink/?LinkID=123415


 CONTENIDO AUTOGENERADO
    El cmdlet Get-Help genera automáticamente el nombre, la sintaxis, 
    la lista de parámetros, la tabla de atributos del parámetro, los 
    parámetros comunes y las notas.

        Nombre: 
            La sección de nombre de un tema de Ayuda de una función 
            se toma del nombre de la función que figura 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 del archivo de script.
 
        Sintaxis: 
            La sección de 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 de .NET Framework de un parámetro, añádalos 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 la función o del script y de las 
            descripciones que se agregan mediante la palabra clave 
            Parameters. Los parámetros de función aparecen en 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 el uso de mayúsculas de los nombres de los 
            parámetros también se toman de la sintaxis; el nombre de 
            parámetro especificado por la palabra clave Parameter no 
            tiene efecto en ello. 

        Parámetros comunes: 
            Los parámetros comunes se agregan a la sintaxis y a 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 del parámetro: 
            Get-Help genera la tabla de atributos del parámetro que 
            aparece cuando se utilizan l os parámetros Full o 
            Parameter de Get-Help. El valor de los atributos 
            Requerido, Posición y Valor predeterminado se toma de la 
            sintaxis de la función o del script. 

        Notas: 
            La sección de notas del tema de Ayuda se genera 
            automáticamente a partir del nombre de la función o del 
            script. Su contenido no se puede modificar ni verse afectado.



 EJEMPLOS

    Ejemplo 1: Ayuda basada en comentarios de una función

        En la función de ejemplo siguiente se incluye Ayuda basada en 
        comentarios:

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

            <#
            .SYNOPSIS 
            Agrega una extensión de nombre de archivo a un nombre 
            proporcionado.

            .DESCRIPTION
            Agrega una extensión de nombre de archivo a un nombre 
            proporcionado. Toma las cadenas para el nombre o la 
            extensión de archivo.

            .PARAMETER Name
            Especifica el nombre del archivo.

            .PARAMETER Extension
            Especifica la extensión. El valor predeterminado es "Txt".

            .INPUTS
            Ninguna. No se pueden canalizar objetos a Add-Extension.

            .OUTPUTS
            System.String. Add-Extension devuelve una cadena con la 
            extensión o el nombre del archivo.

            .EXAMPLE
            C:\PS> extension -name "Archivo"
            Archivo.txt

            .EXAMPLE
            C:\PS> extension -name "Archivo" -extension "doc"
            Archivo.doc

            .EXAMPLE
            C:\PS> extension "Archivo" "doc"
            Archivo.doc

            .LINK
            Versión en pantalla: http://www.fabrikam.com/extension.html

            .LINK
            Set-Item
            #>
            }



        Los resultados son:

        C:\PS> get-help add-extension -full

        NOMBRE
            Add-Extension
    
        SINOPSIS
            Agrega una extensión de nombre de archivo a un nombre 
            proporcionado.
    
        SINTAXIS
            Add-Extension [[-Name] <Cadena>] [[-Extension] <Cadena>] 
            [<CommonParameters>] 
        DESCRIPCIÓN
            Agrega una extensión de nombre de archivo a un nombre 
            proporcionado. Toma las cadenas para el nombre o la 
            extensión de archivo.
    
        PARÁMETROS
           -Name
               Especifica el nombre del archivo.
        
               ¿Requerido?                    false
               ¿Posición?                     0
               Valor predeterminado                
               ¿Aceptar canalización?         false
               ¿Aceptar caracteres comodín?  
        
           -Extension
               Especifica la extensión. El valor predeterminado es "Txt".
        
               ¿Requerido?                    false
               ¿Posición?                     1
               Valor predeterminado                
               ¿Aceptar canalización?         false
               ¿Aceptar caracteres comodín?  
        
            <CommonParameters>
               Este cmdlet admite los parámetros comunes: -Verbose, 
               -Debug, ErrorAction, -ErrorVariable, -WarningAction, 
               -WarningVariable, OutBuffer y -OutVariable. Para obtener 
               más información, escriba "get-help about_commonparameters".
    

        TIPO DE ENTRADA
            Ninguna. No se pueden canalizar objetos a Add-Extension.
    
        SALIDA
            System.String. Add-Extension devuelve una cadena con la 
            extensión o el nombre del archivo.
        
            -------------------------- EJEMPLO 1 -------------------------- 

            C:\PS> extension -name "Archivo"
            Archivo.txt
    
            -------------------------- EJEMPLO 2 -------------------------- 

            C:\PS> extension -name "Archivo" -extension "doc"
            Archivo.doc
    
            -------------------------- EJEMPLO 3 -------------------------- 

            C:\PS> extension "Archivo" "doc"
            Archivo.doc
    
        VÍNCULOS RELACIONADOS
            Versión en pantalla: http://www.fabrikam.com/extension.htm
            l Set-Item



    Ejemplo 2: Descripciones de parámetros en la sintaxis de funciones

        Este ejemplo es igual que el anterior, excepto porque las 
        descripciones de los parámetros se insertan en la sintaxis de 
        la función. Este formato resulta más útil cuando las 
        descripciones son breves. 


        function Add-Extension 
        {
            param 
            (
                [cadena]
                # Especifica el nombre de archivo.
                $name,

                [cadena]
                # Especifica la extensión del nombre de archivo. El valor 
                predeterminado es "Txt".
                $extension = "txt"
            )
            $name = $name + "." + $extension
            $name
      
            <#
            .SYNOPSIS 
            Agrega una extensión de nombre de archivo a un nombre proporcionado.

            .DESCRIPTION
            Agrega una extensión de nombre de archivo a un nombre 
            proporcionado. Toma las cadenas para el nombre o la 
            extensión de archivo.

            .INPUTS
            Ninguna. No se pueden canalizar objetos a Add-Extension.

            .OUTPUTS
            System.String. Add-Extension devuelve una cadena con la 
            extensión o el nombre del archivo.

            .EXAMPLE
            C:\PS> extension -name "Archivo"
            Archivo.txt

            .EXAMPLE
            C:\PS> extension -name "Archivo" -extension "doc"
            Archivo.doc

            .EXAMPLE
            C:\PS> extension "Archivo" "doc"
            Archivo.doc
 
            .LINK
            Versión en pantalla: http://www.fabrikam.com/extension.html

            .LINK
            Set-Item
            #>
        }




    Ejemplo 3: Ayuda basada en comentarios para los scripts

        En el script de ejemplo siguiente se incluye Ayuda basada en comentarios. 

        Observe las líneas en blanco entre los símbolos de cierre "#> 
        " y la instrucción Param. En un script que no tenga una 
        instrucción Param, deberá haber por lo 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 asociará el tema de Ayuda a la función y no al script.

           <#
           .SYNOPSIS 
           Realiza actualizaciones mensuales de datos.

           .DESCRIPTION
           El script Update-Month.ps1 actualiza el Registro con nuevos datos 
           generados durante el mes anterior y genera un informe.
    
           .PARAMETER InputPath
           Especifica la ruta de acceso al archivo de entrada basado en CSV.

           .PARAMETER OutputPath
           Especifica el nombre y la ruta de acceso del archivo de 
           salida basado en CSV. De forma predeterminada, MonthlyUpdates.ps1 
           genera un nombre a partir de la fecha y hora en que se ejecuta y 
           guarda la salida en el directorio local.

           .INPUTS
           Ninguna. No se pueden canalizar objetos a Update-Month.ps1.

           .OUTPUTS
           Ninguna. Update-Month.ps1 no genera ninguna salida.

           .EXAMPLE
           C:\PS> .\Update-Month.ps1

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

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

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

           function Get-Data { }
           ...


        El comando siguiente permite ver la Ayuda del script. Dado 
        que el script no se encuentra en un directorio que figure en 
        la lista de la variable de entorno Path, el comando Get-Help 
        que permite ver la Ayuda del script debe especificar la ruta 
        de acceso del script.


            PS C:\ps-test> get-help .\update-month.ps1 -full

            NOMBRE
                C:\ps-test\Update-Month.ps1
    
            SINOPSIS
                Realiza actualizaciones mensuales de datos.
    
            SINTAXIS
                C:\ps-test\Update-Month.ps1 [-InputPath] <Cadena> 
                [[-OutputPath] ]<Cadena>] [<CommonParameters>]
    
            DESCRIPCIÓN
                El script Update-Month.ps1 actualiza el Registro con 
                nuevos datos generados durante el mes anterior y 
                genera un informe.
    
            PARÁMETROS
               -InputPath
                   Especifica la ruta de acceso al archivo de entrada 
                   basado en CSV.
        
                   ¿Requerido?                    true
                   ¿Posición?                     0
                   Valor predeterminado                
                   ¿Aceptar canalización?         false
                   ¿Aceptar caracteres comodín?  
        
               -OutputPath
                   Especifica el nombre y la ruta de acceso del 
                   archivo de salida basado en CSV. De forma 
                   predeterminada, MonthlyUpdates.ps1 genera un 
                   nombre a partir de la fecha y hora en que se 
                   ejecuta y guarda la salida en el directorio local.
        
                   ¿Requerido?                    false
                   ¿Posición?                     1
                   Valor predeterminado                
                   ¿Aceptar canalización?         false
                   ¿Aceptar caracteres comodín?  
               <CommonParameters>
                   Este cmdlet admite los parámetros comunes: 
                   -Verbose, -Debug, ErrorAction, -ErrorVariable, 
                   -WarningAction, -WarningVariable, OutBuffer y 
                   -OutVariable. Para obtener más información, 
                   escriba "get-help about_commonparameters".
    
            TIPO DE ENTRADA
                   Ninguna. No se pueden canalizar objetos a 
                   Update-Month.ps1.
    
            SALIDA
                   Ninguna. Update-Month.ps1 no genera ninguna salida.
    
    
            -------------------------- EJEMPLO 1 -------------------------- 

            C:\PS> .\Update-Month.ps1
    
            -------------------------- EJEMPLO 2 -------------------------- 

            C:\PS> .\Update-Month.ps1 -inputpath C:\Data\Enero.csv
    
            -------------------------- EJEMPLO 3 -------------------------- 

            C:\PS> .\Update-Month.ps1 -inputpath C:\Data\Enero.csv -outputPath 
            C:\Reports\2009\Enero.csv
        
            VÍNCULOS RELACIONADOS



    Ejemplo 4: Redirigir a un archivo XML

        Es posible escribir temas de Ayuda basada en XML para las 
        funciones y los scripts. Aunque la Ayuda basada en 
        comentarios es más fácil de implementar, es necesario 
        recurrir a la Ayuda basada en XML si se desea controlar con 
        mayor precisión el contenido de la Ayuda o si los temas de la 
        Ayuda se van a traducir a varios idiomas. 

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


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


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

            function Get-Data { }
            ...



       En el ejemplo siguiente se muestra el uso de la palabra clave 
       ExternalHelp en una función.


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


    Ejemplo 5: Redirigir a un tema de Ayuda diferente

        El código siguiente es un extracto del principio de la 
        función Help integrada en Windows PowerShell, que muestra una 
        pantalla de texto de Ayuda cada vez. Dado que el tema de 
        Ayuda correspondiente al cmdlet Get-Help describe la función 
        Help, la función Help utiliza las palabras clave 
        ForwardHelpCategory y ForwardHelpTargetName 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 comando siguiente utiliza esta característica:

            C:\PS> get-help help

            NOMBRE
                Get-Help

            SINOPSIS
                Muestra información acerca de cmdlets y conceptos de 
                Windows PowerShell.
            ...


VEA TAMBIÉN
    about_Functions
    about_Functions_Advanced_Parameters
    about_Scripts
    "Cómo escribir la Ayuda de los cmdlets" 
    (https://go.microsoft.com/fwlink/?LinkID=123415)






Tabla de contenido