Table des matières

, ,

PowerShell : Intégrer l'aide au code

La cmdlet Get-Help peut extraire les commentaires présents dans les scripts (module et les fonctions) et générer / mettre en forme l'aide. La documentation officielle désigne cela par aide basée sur les commentaires.

Aide intégrée aux fonctions

Tous les commentaires ne sont pas extraits pour la génération de l'aide basée sur les commentaires. Dans le cas d'une fonction il faut les placer : 

<#
    .Description
    The MyProcess function gets the Windows PowerShell process.
#>
function MyFunction { Get-Process powershell}
function MyProcess
{
    <#
       .Description
       The MyProcess function gets the Windows PowerShell process.
    #>
 
    Get-Process powershell
}
La méthode recommandée est d'intégrer l'aide basée sur les commentaire directement sous la signature de la fonction comme présenté ci-dessus. Ainsi les commentaires restent liés à la fonction. 
function MyFunction
{
    Get-Process powershell
 
    <#
       .Description
       The MyProcess function gets the Windows PowerShell process.
    #>
}

Le bloc de commentaires utilisés pour la génération de l'aide contiennent des mots clés commençant par un .. Ni l'ordre d’apparition, ni la casse de caractères n'a d'importance.

Quelques mots clés usuels :

.SYNOPSIS Description courte, ne s'utilise qu'une fois par rubrique.
.DESCRIPTION Description détaillée, ne s'utilise qu'une fois par rubrique.
.PARAMETER aParam Description d'un paramètre.
.EXAMPLE Exemple d'utilisation/appel de la fonction ou du script.
.LINK Associer une ou plusieurs rubrique d'aide ou Uri

Troubleshooting

La fonction est bien définie dans l'environnement courant mais les rubriques de l'aide ne sont pas remplies par les commentaires intégrés dans le code.

Ce problème a été rencontré notamment à cause d'une mauvaise syntaxe du mot clé .PARAMETER 

<#
  # Syntaxe invalide!
  .PARAMETER
  aParam Description du paramètre.
 
  # le mot clé .PARAMETER doit être suivi immédiatement par le nom du paramètre
  .PARAMETER aParam
  Description du paramètre ici.
#>

Pour tester la validité de la syntaxe, on peut simplement copier/coller la définition de la fonction dans l'environnement courant. L'appel de Get-Help avec le nom de la fonction doit retourner l'aide correctement formatée.

Références