Différences

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

--- dev:powershell:integration_aide [2023/08/22 10:35] – 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 basée sur les commentaires. Dasn le cas d'une 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 ;
@@ Ligne 36: / Ligne 34: @@
 </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>
@@ Ligne 53: / Ligne 54: @@
 Quelques mots clés usuels :
-^ .SYNOPSIS     | Description courte, ne s'utilise qu'une fois par rubrique.     |
+^ .SYNOPSIS           | Description courte, ne s'utilise qu'une fois par rubrique.     |
-^ .DESCRIPTION  | Description détaillée, ne s'utilise qu'une fois par rubrique.  |
+^ .DESCRIPTION        | Description détaillée, ne s'utilise qu'une fois par rubrique.  |
-^ .PARAMETER    | Description d'un paramètre.                                    |
+^ .PARAMETER aParam   | Description d'un paramètre.                                    |
-^ .EXAMPLE      | Exemple d'utilisation/appel de la fonction ou du script.       |
+^ .EXAMPLE            | Exemple d'utilisation/appel de la fonction ou du script.       |
-^ .LINK         | Associer une ou plusieurs rubrique d'aide ou Uri               |
+^ .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 =====
@@ Ligne 65: / Ligne 86: @@
   * [[ 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