Cette page a été traduite par l'API Cloud Translation.

Mettre à jour les commandes OT CLI

<ph type="x-smartling-placeholder"></ph> Consulter le code source sur GitHub

Nous générons des commandes CLI à partir des fichiers sources de la CLI openthread dépôt GitHub.

Ce guide explique comment utiliser nos commentaires Doxygen personnalisés que nous utilisons pour créer la liste de commandes.

Commencer

Pour documenter une commande CLI, procédez comme suit. Il est important que suivez ces étapes dans l'ordre indiqué.

Rechercher l'élément Cmd associé dans openthread/src/cli . Par exemple, pour trouver ba state, recherchez Cmd("ba"). Chaque commande sera associée à un modèle de fonction:
```
template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])
```
Dans le modèle de fonction, localisez la logique de commande correcte. Par exemple, ba state :
```
else if (aArgs[0] == "state")
```
Avant que la logique ne commence, démarrez le bloc Doxygen @cli:
```
/**
 * @cli ba state
```
Ensuite, juste en dessous de @cli, ajoutez des exemples en utilisant @code. Inclure à au moins un exemple. N'incluez pas l'invite > et assurez-vous de documenter le résultat renvoyé complet, y compris la réponse Done standard.
```
 * @code
 * ba state
 * Started
 * Done
 * @endcode
```

Comme les commandes CLI fournissent un accès en ligne de commande aux méthodes d'API courantes et fonctions, certaines commandes partagent la même description l'API correspondante. Si la description de la commande est identique, effectuez la procédez comme suit:

Recherchez l'API associée dans openthread/include/openthread . Par exemple, ba state correspond à otBorderAgentGetState.
Exécutez la commande api_copy, puis saisissez le nom de l'API juste en dessous. Avant la définition de l'API, veillez à utiliser le signe dièse #. pour créer le lien automatique Doxygen.
```
@par api_copy
#otBorderAgentGetState
```

Voici un exemple complet des commentaires Doxygène minimaux requis pour générer automatiquement une commande OT CLI:

/**
 * @cli ba state
 * @code
 * ba state
 * Started
 * Done
 * @endcode
 * @par api_copy
 * #otBorderAgentGetState
 */

Pour examiner la sortie HTML, reportez-vous à État BA. Pour obtenir des exemples avancés et des options supplémentaires, consultez les sections suivantes.

Options de modèle de CLI

Les commandes CLI sont regroupées dans un seul bloc de commentaires continu, commençant par Balise ALIAS @cli. Plusieurs exemples @code sont acceptés.

L'ordre dans lequel vous spécifiez chaque balise est important.

@cparam doit être postérieur à @code
Si vous copiez une description d'API, @par api_copy doit être placé après @cparam

 * @cli command name (overload1,overload2)
 * @code
 * command name arg1
 * Done
 * @endcode
 * @cparam command name @ca{arg1} [@ca{opt-arg}] [@ca{choose-1}|@ca{choose-2}]
 * Optional parameter description; displays below the Parameter heading.
 * *   Markdown and lists are supported.
 * @par api_copy
 * #{apiName}
 * @par
 * Optional CLI specific paragraph. Markdown and lists are supported.
 * @note Notes are supported.
 * @csa{other command name}
 * @sa API method or function name

Découvrez à présent comment chaque balise ALIAS est utilisée.

Noms des commandes

Tout texte après @cli devient l'en-tête du nom de la commande. Cet en-tête est utilisé dans les liens dynamiques (par exemple, Préfixe de publication netdata :

 * @cli netdata publish prefix

</ph>
Important: N'utilisez pas d'arguments ni de caractères spéciaux dans les noms de commandes.

D'autres commandes peuvent être plus complexes. Par exemple : netdata publish dnssrp unicast propose plusieurs options:

Publication par adresse et numéro de port
Publier par numéro de port et par EID local maillé d'un appareil

Si une commande est surchargée, utilisez des parenthèses pour l'identifier de manière unique.

 * @cli netdata publish dnssrp unicast (mle)
 * @cli netdata publish dnssrp unicast (addr,port)

Descriptions des commandes

Il existe trois façons de documenter la description des commandes. Vous pouvez copier le la description de l'API, utilisez celle-ci, mais ajoutez des informations supplémentaires ; ou fournir une description totalement unique qui appartient uniquement au . Dans les sections suivantes, nous allons passer en revue chaque méthode.

Copiez la description de l'API correspondante.

Utilisez api_copy pour copier la méthode ou la fonction d'API correspondante. Quand ? vous copiez les API, assurez-vous que la description convient à la fois et la commande CLI. Évitez d'utiliser des expressions qui ne s'appliquent qu'à (par exemple, This function ou This method). Préférer une voix active, par exemple Gets the ou Sets the.

 * @par api_copy
 * #otBorderAgentGetState

Ajouter des informations à la description de l'API

Si vous souhaitez utiliser api_copy, mais que vous devez ajouter des informations supplémentaires ne s'applique qu'à la commande CLI, utilisez @par. Après la balise @par, assurez-vous que pour passer à la ligne suivante.

 * @par api_copy
 * #otBorderAgentGetState
 * @par
 * CLI description here; add a few things that do not apply to the API method.
 * @par
 * Start a new paragraph.

Ces paragraphes s'affichent après la description de l'API.

Fournir des descriptions spécifiques à la CLI uniquement

Certaines commandes CLI utilisent plusieurs API ou diffèrent de l'appel d'API. D'autres ne sont pas associés à une API, par exemple netdata help. Pour fournir une description distincte, utilisez @par. N'incluez pas de titre en @par et commencez votre description à ligne. Dans ce scénario, n'utilisez pas @api_copy.

/**
 * @cli netdata help
 * @code
 * netdata help
 * ...
 * show
 * steeringdata
 * unpublish
 * Done
 * @endcode
 * @par
 * Gets a list of `netdata` CLI commands.
 */

Paramètres

Définissez les paramètres de commande à l'aide de @cparam et de @ca.

Insérez des crochets ([ ]) autour des arguments facultatifs.
Utilisez des barres verticales | (barre verticale) entre les choix d'arguments.
Pour afficher les détails des paramètres, vous pouvez saisir des phrases et des listes Markdown sous la balise @cparam.

Paramètres avec détails

 * @cparam netdata publish prefix @ca{prefix} [@ca{padcrosnD}] [@ca{high}|@ca{med}|@ca{low}]
 * OT CLI uses mapped arguments to configure #otBorderRouterConfig values. @moreinfo{the @overview}.

Pour examiner la sortie HTML, reportez-vous au préfixe de publication netdata.

Paramètres avec des listes Markdown

Vous pouvez également utiliser des listes après le @cparam. Cela est utile lorsque vous souhaitez fournir des détails sur les arguments de commande utilisés.

 * @cparam netdata show [@ca{local}] [@ca{-x}]
 * *   The optional `-x` argument gets Network Data as hex-encoded TLVs.
 * *   The optional `local` argument gets local Network Data to sync with Leader.

Pour examiner la sortie HTML, reportez-vous à netdata show.

Les blocs @cli doivent être un commentaire continu sans espaces. Si vous ajoutez une liste sous @cparam et si vous avez besoin d'un autre paragraphe en dessous de cette liste, utilisez un point . pour mettre fin manuellement à la liste.

* @cparam commandname [@ca{qmr}]
* [`q`, `m`, and `r`] map to #otLinkMetricsValues.
* *   `q`: Layer 2 LQI (#otLinkMetricsValues::mLqiValue).
* *   `m`: Link Margin (#otLinkMetricsValues::mLinkMarginValue).
* *   `r`: RSSI (#otLinkMetricsValues::mRssiValue).
* .
* Add another paragraph here. The dot above will end the HTML list that's generated.
* This paragraph displays under the Parameters heading, and not the command description.

Pour d'autres exemples, consultez Listes :

Associer automatiquement des API

Vous pouvez créer une association avec d'autres méthodes ou fonctions d'API avec #otFunctionName ou @sa Saisissez ces liens à la fin du bloc de commentaires de la CLI.

/**
 * @cli netdata publish prefix
 * @code
 * netdata publish prefix fd00:1234:5678::/64 paos med
 * Done
 * @endcode
 * @cparam netdata publish prefix @ca{prefix} [@ca{padcrosnD}] [@ca{high}|@ca{med}|@ca{low}]
 * OT CLI uses mapped arguments to configure #otBorderRouterConfig values. @moreinfo{the @overview}.
 * @par
 * Publish an on-mesh prefix entry. @moreinfo{@netdata}.
 * @sa otNetDataPublishOnMeshPrefix
 */

Les liens @sa s'affichent dans l'en-tête Documentation de référence sur les CLI et les API. Pour revoir le code HTML de sortie, consultez Préfixe de publication netdata.

Empêcher les associations automatiques

Parfois, Doxygen peut confondre un mot normal comme un lien vers une classe CLI, par le mot Joiner, par exemple. Pour empêcher Doxygen d’établir un lien avec des mots clés ou une classe utilisez l'opérateur % devant le mot concerné, Par exemple:

Clear the %Joiner discerner

Pour en savoir plus, consultez Génération automatique d'associations dans le guide sur Doxygen.

Associer automatiquement d'autres commandes

Utilisez @csa pour associer d'autres commandes.

* @csa{netdata publish dnssrp anycast}

Si une commande est surchargée, incluez les parenthèses et ajoutez une virgule le cas échéant. N'utilisez pas d'espaces entre les parenthèses:

* @csa{netdata publish dnssrp unicast (addr,port)}
* @csa{netdata publish dnssrp unicast (mle)}

Commandes spéciales Doxygen

Les commandes CLI prennent en charge les ALIASES Doxygen suivants et les commandes spéciales suivantes:

ALIAS	Exemple	Description
@cli	@cli ba port	Nom de la commande. Démarre un bloc de commentaires dans la CLI.
@code	@code ba port 41953 Terminé @endcode	Exemple de commande
@ca	[@ca{préfixe}]	Argument de commande. Utilisez des crochets `[ ]` pour les arguments facultatifs.
@cparam	@cparam joiner discerner @ca{discerner} Détails du paramètre.	Paramètres de la commande.
@par	@par Description de la CLI facultative.	Paragraphes spécifiques à la CLI.
@csa	@csa{prefix add}	Commande Voir aussi. Lien vers une autre commande.
@sa	@sa otBorderRouterConfig	Voir aussi. Crée un lien vers une documentation de référence d'API.
@présentation	@présentation	Crée un lien vers la présentation de la CLI OpenThread.
@netdata	@netdata	Crée un lien vers Display and Manage Network Data with OT CLI.
@dataset	@dataset	Crée un lien vers Display and Manage Datasets with OT CLI (Afficher et gérer les ensembles de données avec la CLI OT).
@udp	@udp	Crée un lien vers Tester la fonctionnalité UDP avec la CLI OT.
@moreinfo	@moreinfo{@netdata}	Crée un lien de parrainage.
@note	Remarque importante @note.	Crée une zone de texte pour les notes.

Corriger les lignes rompues par le script `make pretty`

Certains commentaires sur le code, tels que les paramètres CLI ou le résultat de la commande, doivent être activés une seule ligne pour qu'ils s'affichent correctement dans la référence openthread.io. Cependant, make pretty impose une limite de largeur de colonne, ce qui peut endommager le rendu pour les longues lignes.

Pour résoudre ce problème, ajoutez des sauts de ligne avec une balise de commentaire HTML, comme illustré dans les deux exemples ci-dessous.

Le premier exemple est la commande dns resolve, qui peut prendre jusqu'à six paramètres. Pour rendre correctement la syntaxe à l'aide de Doxygen tout en transmettant la vérification make pretty, les paramètres doivent être répartis sur trois lignes dans la source:

* @cparam dns resolve @ca{hostname} [@ca{dns-server-IP}] <!--
* -->                 [@ca{dns-server-port}] [@ca{response-timeout-ms}] <!--
* -->                 [@ca{max-tx-attempts}] [@ca{recursion-desired-boolean}]

Le deuxième exemple est la sortie de la commande history ipaddr list 5. Pour que la sortie s'affiche correctement tout en réussissant la vérification make pretty, chacune des cinq lignes de sortie doit être divisée en deux lignes, comme suit:

* history ipaddr list 5
* 00:00:20.327 -> event:Removed address:2001:dead:beef:cafe:c4cb:caba:8d55:e30b <!--
* -->prefixlen:64 origin:slaac scope:14 preferred:yes valid:yes rloc:no
* 00:00:59.983 -> event:Added address:2001:dead:beef:cafe:c4cb:caba:8d55:e30b <!--
* -->prefixlen:64 origin:slaac scope:14 preferred:yes valid:yes rloc:no
* 00:01:22.535 -> event:Added address:fd00:0:0:0:0:0:0:1 prefixlen:64 <!--
* -->origin:manual scope:14 preferred:yes valid:yes rloc:no
* 00:02:33.221 -> event:Added address:fdde:ad00:beef:0:0:ff:fe00:fc00 <!--
* -->prefixlen:64 origin:thread scope:3 preferred:no valid:yes rloc:no
* 00:02:33.221 -> event:Added address:fdde:ad00:beef:0:0:ff:fe00:5400 <!--
* -->prefixlen:64 origin:thread scope:3 preferred:no valid:yes rloc:yes
* Done