Aggiornamento comandi interfaccia a riga di comando OT

Visualizza il codice sorgente su GitHub

Generiamo i comandi dell'interfaccia a riga di comando dai file di origine dell'interfaccia a riga di comando nel repository GitHub di openthread.

Questa guida fornisce istruzioni su come utilizzare i nostri commenti Doxygen personalizzati che utilizziamo per creare l'elenco di comandi.

Inizia

Per documentare un comando dell'interfaccia a riga di comando, completa i passaggi seguenti. È importante seguire questi passaggi nell'ordine indicato.

  1. Trova il Cmd associato nella directory openthread/src/cli. Ad esempio, per trovare ba state, cerca Cmd("ba"). A ogni comando sarà associato un modello di funzione:

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

  2. Nel modello della funzione, individua la logica di comando corretta. Ad esempio, ba state:

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

  3. Prima che inizi la logica, avvia il blocco Doxygen @cli:

    /**
 * @cli ba state

  4. Quindi, subito sotto @cli, aggiungi esempi utilizzando @code. Includi almeno un esempio. Non includere il prompt > e assicurati di documentare l'output di ritorno completo, inclusa la risposta Done standard.

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

Poiché i comandi dell'interfaccia a riga di comando forniscono l'accesso da riga di comando a metodi e funzioni dell'API comuni, alcuni condividono la stessa descrizione dell'API corrispondente. Se la descrizione del comando è la stessa, completa i seguenti passaggi:

  1. Trova l'API associata nella directory openthread/include/openthread. Ad esempio, ba state viene mappato a otBorderAgentGetState.

  2. Utilizza il comando api_copy e inserisci il nome dell'API direttamente sotto. Prima della definizione dell'API, assicurati di utilizzare il simbolo di cancelletto # per creare il link Doxygen automatico.

    @par api_copy
#otBorderAgentGetState

Ecco un esempio completo dei commenti minimi Doxygen necessari per generare automaticamente un comando OT CLI:

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

Per esaminare l'output HTML, fai riferimento alla sezione Stato ba. Per esempi avanzati e opzioni aggiuntive, consulta le sezioni seguenti.

Opzioni dei modelli dell'interfaccia a riga di comando

I comandi dell'interfaccia a riga di comando sono raggruppati in un blocco di commenti continuo, a partire dal tag ALIAS @cli. Sono supportati più esempi di @code.

L'ordine in cui specifichi ogni tag è importante.

  • @cparam deve essere successiva al giorno @code
  • Se stai copiando una descrizione dell'API, @par api_copy deve essere inserito dopo il giorno @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

Successivamente, scopri di più sul modo in cui viene utilizzato ogni tag ALIAS.

Nomi dei comandi

Qualsiasi testo dopo @cli diventa l'intestazione del nome del comando. Questa intestazione viene utilizzata nel collegamento dinamico, ad esempio il comando prefisso netdata publish:

 * @cli netdata publish prefix

Altri comandi potrebbero essere più complessi. Ad esempio, netdata publish dnssrp unicast offre alcune opzioni:

  1. Pubblica tramite indirizzo e numero di porta
  2. Pubblicazione tramite numero di porta e EID locale mesh del dispositivo

Se un comando è sovraccarico, utilizza le parentesi per identificarlo in modo univoco.

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

Descrizioni dei comandi

Esistono tre modi per documentare le descrizioni dei comandi. Puoi copiare la descrizione dell'API, utilizzare la descrizione dell'API, ma aggiungere ulteriori informazioni o fornire una descrizione completamente univoca che appartenga solo al comando dell'interfaccia a riga di comando. Nelle sezioni successive esamineremo ogni metodo.

Copia la descrizione dell'API corrispondente

Utilizza api_copy per copiare il metodo o la funzione API corrispondente. Quando copi le API, assicurati che la descrizione funzioni sia per l'API sia per il comando dell'interfaccia a riga di comando. Evita di utilizzare frasi che si applicano solo a una funzione, ad esempio This function o This method. Preferisci una voce attiva, ad esempio Gets the o Sets the.

 * @par api_copy
 * #otBorderAgentGetState

Aggiungi ulteriori informazioni alla descrizione dell'API

Se vuoi utilizzare api_copy, ma devi aggiungere ulteriori informazioni che si applicano solo al comando dell'interfaccia a riga di comando, utilizza @par. Dopo il tag @par, assicurati di passare alla riga successiva.

 * @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.

Questi paragrafi vengono visualizzati dopo la descrizione dell'API.

Fornisci solo descrizioni specifiche per l'interfaccia a riga di comando

Alcuni comandi dell'interfaccia a riga di comando utilizzano più API o sono diversi dalla chiamata API. Altre non hanno un'API associata, ad esempio netdata help. Per fornire una descrizione separata, utilizza @par. Non includere un titolo @par e inizia la descrizione nella riga successiva. In questo caso, non utilizzare @api_copy.

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

Parametri

Definisci i parametri di comando utilizzando @cparam e @ca.

  • Racchiudi gli argomenti facoltativi tra parentesi [ ].
  • Utilizza le barre verticali | (pipe) tra le scelte degli argomenti.
  • Per visualizzare i dettagli dei parametri, puoi inserire frasi ed elenchi di markdown sotto il tag @cparam.

Parametri con dettagli

 * @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}.

Per esaminare l'output HTML, fai riferimento a Prefisso pubblicazione netdata.

Parametri con elenchi di markdown

Puoi anche utilizzare elenchi successivi al giorno @cparam. Ciò è utile per fornire dettagli sugli argomenti dei comandi utilizzati.

 * @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.

Per esaminare l'output HTML, consulta netdata show.

I blocchi @cli devono essere un commento continuo senza spazi. Se aggiungi un elenco inferiore a @cparam e poi hai bisogno di un altro paragrafo sotto l'elenco, utilizza un punto . per terminare manualmente l'elenco.

* @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.

Per ulteriori esempi, consulta gli elenchi di Doxygen.

Puoi collegarti ad altri metodi o funzioni dell'API con #otFunctionName o @sa. Inserisci questi link alla fine del blocco dei commenti dell'interfaccia a riga di comando.

/**
 * @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
 */

I link @sa vengono visualizzati nell'intestazione CLI e riferimenti API. Per esaminare l'output HTML, consulta la sezione Prefisso pubblicazione netdata.

A volte, Doxygen può scambiare una parola normale come un link a una classe interfaccia a riga di comando, ad esempio, la parola Joiner. Per impedire che Doxygen si colleghi alle parole chiave o ai nomi di classi utilizzati in una frase, utilizza l'operatore % davanti alla parola, ad esempio:

Clear the %Joiner discerner

Per ulteriori informazioni, consulta la sezione Generazione automatica di collegamenti nella guida di Doxygen.

Usa @csa per collegarti ad altri comandi.

* @csa{netdata publish dnssrp anycast}

Se un comando è sovraccarico, includi le parentesi e aggiungi una virgola, se applicabile. Non utilizzare spazi all'interno delle parentesi:

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

Comandi speciali Doxygen

I comandi dell'interfaccia a riga di comando supportano i seguenti comandi Doxygen ALIASES e speciali:

ALIAS Esempio Descrizione
@cli Porta ba @cli Nome del comando. Avvia un blocco di commenti dell'interfaccia a riga di comando.
@codice @code
porta ba
41953
Fine
@endcode		 Esempio di comando.
@ca [@ca{prefix}] Argomento del comando. Utilizza le parentesi [ ] per gli argomenti facoltativi.
@cparam @cparam joiner discerner @ca{discerner}
Dettagli parametro.		 Parametri del comando.
@par @par
Descrizione facoltativa dell'interfaccia a riga di comando.		 Paragrafi specifici dell'interfaccia a riga di comando.
@csa @csa{prefix add} Comando Vedi anche. Link a un altro comando.
@sa otBorderRouterConfig @sa Vedi anche. Crea un link a un riferimento API.
@panoramica @panoramica Crea un link alla Panoramica dell'interfaccia a riga di comando OpenThread.
@netdata @netdata Crea un link a Visualizza e gestisci i dati di rete con OT CLI.
@set di dati @set di dati Crea un link per visualizzare e gestire i set di dati con OT CLI.
@udp @udp Crea un link a Testare la funzionalità UDP con interfaccia a riga di comando OT.
@moreinfo @moreinfo{@netdata} Crea un link del referral.
@nota @note Callout importante. Crea una casella di callout per le note.

Correzione delle righe interrotte dallo script make pretty

Alcuni commenti del codice, come i parametri dell'interfaccia a riga di comando o l'output dei comandi, devono trovarsi su una singola riga affinché possano essere visualizzati correttamente nel riferimento openthread.io. Tuttavia, make pretty impone un limite di larghezza della colonna, che può interrompere l'output visualizzato per le righe lunghe.

Questa situazione può essere risolta aggiungendo interruzioni di riga e racchiudendole in un tag di commento HTML, come illustrato nei due esempi riportati di seguito.

Il primo esempio è il comando dns resolve, che può utilizzare fino a sei parametri. Per visualizzare correttamente la sintassi utilizzando Doxygen pur passando il controllo make pretty, i parametri devono essere suddivisi su tre righe nell'origine:

* @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}]

Il secondo esempio è l'output del comando history ipaddr list 5. Affinché l'output venga visualizzato correttamente e superi comunque il controllo make pretty, ciascuna delle cinque righe di output deve essere suddivisa in due righe, come segue:

* 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