ProvideCommentHelp

Nivel de gravedad de : de información

Descripción

Se debe proporcionar ayuda basada en comentarios para todos los comandos de PowerShell. Esta prueba solo comprueba la presencia de ayuda basada en comentarios y no en la validez o el formato.

Para obtener ayuda sobre la ayuda basada en comentarios, use el comando Get-Help about_comment_based_help o los siguientes artículos:

• escribir ayuda basada en comentarios
• escribir ayuda para cmdlets de PowerShell
• ayuda basada en XML mediante platyPS

Configuración

Rules = @{
    PSProvideCommentHelp = @{
        Enable = $true
        ExportedOnly = $false
        BlockComment = $true
        VSCodeSnippetCorrection = $false
        Placement = 'before'
    }
}

Parámetros

• Enable: bool (el valor predeterminado es $true)

  Habilite o deshabilite la regla durante la invocación de ScriptAnalyzer.

• ExportedOnly: bool (el valor predeterminado es $true)

  Si está habilitada, inicie una infracción solo en funciones o cmdlets que se exportan mediante el cmdlet Export-ModuleMember.

• BlockComment: bool (el valor predeterminado es $true)

  Si está habilitado, devuelve ayuda de comentario en el estilo de comentario de bloque (<#...#>). De lo contrario, devuelve ayuda de comentario en el estilo de comentario de línea donde cada línea de comentario comienza con #.

• VSCodeSnippetCorrection: bool (el valor predeterminado es $false)

  Si está habilitado, devuelve ayuda de comentario en formato de fragmento de código vscode.

• Placement: cadena (el valor predeterminado es before)

  Representa la posición de la ayuda de comentario con respecto a la definición de función.

  Los valores posibles son:

  • before: significa que la ayuda se coloca antes de la definición de la función.
  • begin significa que la ayuda se coloca al principio del cuerpo de la definición de función.
  • end significa que la ayuda está colocando el final del cuerpo de la definición de función

  Si se da algún valor no válido, la propiedad tiene como valor predeterminado before.

Ejemplo

Incorrecto

function Get-File
{
    [CmdletBinding()]
    Param
    (
        ...
    )

}

Correcto

<#
.Synopsis
    Short description
.DESCRIPTION
    Long description
.EXAMPLE
    Example of how to use this cmdlet
.EXAMPLE
    Another example of how to use this cmdlet
.INPUTS
    Inputs to this cmdlet (if any)
.OUTPUTS
    Output from this cmdlet (if any)
.NOTES
    General notes
.COMPONENT
    The component this cmdlet belongs to
.ROLE
    The role this cmdlet belongs to
.FUNCTIONALITY
    The functionality that best describes this cmdlet
#>

function Get-File
{
    [CmdletBinding()]
    Param
    (
        ...
    )

}