Différences

Ci-dessous, les différences entre deux révisions de la page.

--- dev:powershell:integration_aide [2023/08/21 10:00] – yoann
+++ dev:powershell:integration_aide [2023/08/27 23:13] (Version actuelle) – yoann
@@ Ligne 1: / Ligne 1: @@
 {{tag>dev powershell aide}}
-:TODO:
 ====== 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 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 de la fonction, il faut les placer :
+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)]]

wikinotes

Outils pour utilisateurs

Outils du site

Différences

Outils de la page