{{tag>dev powershell aide}}

====== 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 :
  * En entête de la définition de la fonction ;
  * Sur la première ligne sous la signature de la fonction ;
  * Sur la dernière ligne avant la fermeture de la fonction.

<code powershell>
<#
    .Description
    The MyProcess function gets the Windows PowerShell process.
#>
function MyFunction { Get-Process powershell}
</code>


<code powershell>
function MyProcess
{
    <#
       .Description
       The MyProcess function gets the Windows PowerShell process.
    #>

    Get-Process powershell
}
</code>

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

<code powershell>
function MyFunction
{
    Get-Process powershell

    <#
       .Description
       The MyProcess function gets the Windows PowerShell process.
    #>
}
</code>

Le bloc de commentaires utilisés pour la génération de l'aide contiennent des **mots clés** commençant par un <key>.</key>. 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 

<code powershell>
<#
  # 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.
#>
</code> 

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

  * https://learn.microsoft.com/en-us/powershell/scripting/developer/help/writing-help-for-windows-powershell-scripts-and-functions?view=powershell-5.1
  * [[ https://learn.microsoft.com/fr-fr/powershell/module/microsoft.powershell.core/about/about_comment_based_help?view=powershell-7.3|A propos de l'aide basée sur les commentaires (Microsoft Learn)]]
  * [[https://learn.microsoft.com/fr-fr/powershell/scripting/developer/help/comment-based-help-keywords?view=powershell-5.1|Mots clés de l'aide basée sur les commentaires (Microsoft Learn)]]
  * [[https://learn.microsoft.com/en-us/powershell/scripting/developer/help/examples-of-comment-based-help?view=powershell-7.3|Exemples d'aide basée sur les commentaires (Microsoft Learn)]]