Mettre à jour les commandes OT CLI

Consulter la source sur GitHub

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

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

Premiers pas

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

  1. Recherchez l'élément Cmd associé dans le répertoire openthread/src/cli. Par exemple, pour trouver ba state, recherchez Cmd("ba"). Chaque commande est associée à un modèle de fonction:

    template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])

  2. Dans le modèle de fonction, localisez la logique de commande correcte. Par exemple, ba state :

    else if (aArgs[0] == "state")

  3. Avant que la logique ne commence, démarrez le bloc Doxygen @cli:

    /**
 * @cli ba state

  4. Ensuite, juste en dessous de @cli, ajoutez des exemples à l'aide de @code. Incluez au moins un exemple. N'incluez pas l'invite > et assurez-vous de documenter le résultat complet, y compris la réponse Done standard.

     * @code
 * ba state
 * Started
 * Done
 * @endcode

Étant donné que les commandes CLI permettent d'accéder via la ligne de commande aux méthodes et fonctions courantes d'API, certaines commandes partagent la même description que l'API correspondante. Si la description de la commande est identique, procédez comme suit:

  1. Recherchez l'API associée dans le répertoire openthread/include/openthread. Par exemple, ba state correspond à otBorderAgentGetState.

  2. Exécutez la commande api_copy, puis saisissez le nom de l'API directement en dessous. Devant la définition de l'API, assurez-vous d'utiliser le signe dièse # pour créer le lien Doxygen automatique.

    @par api_copy
#otBorderAgentGetState

Voici un exemple complet des commentaires Doxygen 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 à la section État ba. Pour obtenir des exemples avancés et des options supplémentaires, consultez les sections suivantes.

Options du modèle de CLI

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

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

  • @cparam doit être postérieure à @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

Voyons ensuite comment chaque tag ALIAS est utilisé.

Noms des commandes

Tout texte situé 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 la commande netdata publishprefix:

 * @cli netdata publish prefix

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

  1. Publier par adresse et par numéro de port
  2. Publier par numéro de port et EID maillé local 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 les descriptions de commandes. Vous pouvez copier la description de l'API, l'utiliser, mais ajouter des informations supplémentaires, ou fournir une description complètement unique qui appartient uniquement à la commande CLI. Dans les sections suivantes, nous passerons en revue chaque méthode.

Copier la description de l'API correspondante

Utilisez api_copy pour copier la méthode ou la fonction API correspondante. Lorsque vous copiez des API, assurez-vous que la description fonctionne à la fois pour l'API et pour la commande CLI. Évitez d'utiliser des expressions qui ne s'appliquent qu'à une fonction, comme This function ou This method. Préférez 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 qui ne s'appliquent qu'à la commande CLI, utilisez @par. Après la balise @par, veillez à 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 uniquement des descriptions spécifiques à la CLI

Certaines commandes CLI utilisent plusieurs API ou diffèrent de l'appel d'API. D'autres ne sont pas associées à une API, par exemple netdata help. Pour fournir une description distincte, utilisez @par. N'incluez pas de titre @par et commencez votre description sur la ligne suivante. Dans ce cas, 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 @ca.

  • Placez 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 @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, consultez netdata show.

Les blocs @cli doivent correspondre à un commentaire continu sans espaces. Si vous ajoutez une liste en dessous de @cparam et que vous avez ensuite besoin d'un autre paragraphe en dessous de cette liste, utilisez un point . pour terminer 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 obtenir des exemples supplémentaires, consultez les listes de Doxygen.

Vous pouvez créer des liens vers 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 CLI and API References (Documentation de référence sur la CLI et l'API). Pour examiner la sortie HTML, reportez-vous au préfixe de publication netdata.

Parfois, Doxygen peut confondre un mot normal comme un lien vers une classe de CLI (par exemple, le mot Joiner). Pour empêcher Doxygen de créer des liens vers des mots clés ou des noms de classe utilisés dans une phrase, utilisez l'opérateur % devant le mot, par exemple:

Clear the %Joiner discerner

Pour en savoir plus, consultez la section Génération automatique de liens du guide Doxygen.

Utilisez @csa pour créer un lien vers 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 sont compatibles avec les commandes spéciales et les ALIASES Doxygen suivantes:

ALIAS Exemple Description
@cli Port BA @cli Nom de la commande. Démarre un bloc de commentaires de la CLI.
@code @code
port ba
41953
Terminé
@endcode		 Exemple de commande
@ca [@ca{prefix}] l'argument de commande. Utilisez des crochets [ ] pour les arguments facultatifs.
@cparam @cparam joiner discerner @ca{discerner}
Détails du paramètre.		 Paramètres de commande.
@par @par
Description facultative de la CLI.		 Paragraphes spécifiques à la CLI.
@csa @csa{prefix add} Commande Voir aussi. Redirige 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.
@ensemble de données @ensemble de données Crée un lien vers Display and Manage Datasets with OT CLI.
@udp @udp Crée un lien vers Tester la fonctionnalité UDP avec OT CLI.
@plus d'infos @moreinfo{@netdata} Crée un lien de parrainage.
@note @note Accroche importante. Crée une zone d'accroche pour une note.

Corriger les lignes interrompues par le script make pretty

Certains commentaires de code, tels que les paramètres de CLI ou la sortie de commande, doivent figurer sur 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 interrompre le rendu du résultat pour les longues lignes.

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

Le premier exemple est la commande dns resolve, qui peut accepter jusqu'à six paramètres. Pour afficher correctement la syntaxe à l'aide de Doxygen tout en réussissant 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 le résultat de la commande history ipaddr list 5. Pour que la sortie s'affiche correctement et réussisse 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