Aggiornamento comandi interfaccia a riga di comando OT

Visualizza il codice sorgente su GitHub

Generiamo comandi CLI dai file di origine dell'interfaccia a riga di comando aprithread GitHub di ASL.

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

Inizia

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

1. Trova il Cmd associato in 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 dell'inizio della logica, avvia il blocco Doxygen @cli:

   /**
    * @cli ba state
   

4. Poi, immediatamente sotto @cli, aggiungi esempi utilizzando @code. Includi in 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 ai metodi API più comuni e funzioni, alcuni comandi condividono la stessa descrizione l'API corrispondente. Se la descrizione del comando è la stessa, completa la seguenti passaggi:

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

2. Usa il comando api_copy, poi inserisci il nome dell'API direttamente sotto il comando. Assicurati di utilizzare il simbolo del cancelletto # davanti alla definizione dell'API. per creare il collegamento automatico a Doxygen.

   @par api_copy
   #otBorderAgentGetState
   

Ecco un esempio completo del numero minimo di commenti Doxygen richiesti per genera automaticamente un comando OT CLI:

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

Per esaminare l'output HTML, consulta ba state. 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 vengono raggruppati in base a un blocco di commenti continuo, che inizia con 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 la descrizione di un'API, deve essere inserito dopo @par api_copy @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

Ora, scopri come viene utilizzato ogni tag ALIAS.

Nomi dei comandi

Qualsiasi testo dopo @cli diventa l'intestazione del nome del comando. Questa intestazione è utilizzata in sui collegamenti dinamici, ad esempio prefisso pubblicazione netdata :

 * @cli netdata publish prefix

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

1. Pubblica per indirizzo e numero di porta
2. Pubblicazione tramite numero di porta e EID mesh-locale 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

Ci sono tre modi per documentare le descrizioni dei comandi. Puoi copiare la descrizione dell'API, ma aggiungine altre informazioni. o fornire una descrizione completamente unica che appartiene esclusivamente dell'interfaccia a riga di comando. Nelle sezioni successive, esamineremo i singoli metodi.

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 il tramite l'API e il comando dell'interfaccia a riga di comando. Evita di usare frasi che riguardano solo una , ad esempio This function o This method. Preferenza 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 applica solo al comando dell'interfaccia a riga di comando, usa @par. Dopo il tag @par, assicurati per 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 nel prossimo dalla riga di comando. In questo scenario, 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 del comando utilizzando @cparam e @ca.

• Racchiudi tra parentesi [ ] gli argomenti facoltativi.
• Utilizza barre verticali | (linee guida) tra gli argomenti da scegliere.
• Per visualizzare i dettagli dei parametri, puoi inserire frasi ed elenchi 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, consulta la sezione Prefisso di pubblicazione netdata.

Parametri con elenchi Markdown

Puoi anche utilizzare gli elenchi dopo il giorno @cparam. Questa funzionalità è utile per fornisce 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 di @cli devono essere costituiti da un solo commento continuo senza spazi. Se aggiungi un elenco sotto @cparam e poi è necessario un altro paragrafo sotto l'elenco, usa 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, fai riferimento all'elenco Elenchi.

Collegare automaticamente le API

Puoi collegarti ad altri metodi o funzioni dell'API con #otFunctionName oppure @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 interfaccia a riga di comando e riferimenti alle API. Per esaminare il codice HTML l'output, fai riferimento prefisso pubblicazione netdata.

Impedire i link automatici

A volte, Doxygen potrebbe scambiare una parola normale per un link a una classe dell'interfaccia a riga di comando, per ad esempio la parola Joiner. Per impedire a Doxygen di collegarsi a parole chiave o classi nomi utilizzati in una frase, usa l'operatore % davanti alla parola, Ad esempio:

Clear the %Joiner discerner

Per ulteriori informazioni, consulta Generazione automatica di link nella guida Doxygen.

Link automatico ad altri comandi

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 tra 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 le seguenti ALIAS Doxygen e i comandi speciali:

Correggere le righe interrotte dallo script make pretty

Alcuni commenti al codice, come i parametri dell'interfaccia a riga di comando o l'output comando, devono essere attivi su una singola riga affinché il rendering venga eseguito correttamente nel riferimento openthread.io. Tuttavia, make pretty impone un limite di larghezza delle colonne, che può interrompere il rendering per le lunghe righe.

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

Il primo esempio è il comando dns resolve, che può richiedere fino a sei parametri. eseguire correttamente il rendering della sintassi utilizzando Doxygen continuando a trasmettere il controllo make pretty, i parametri devono essere suddivisi su tre righe nel codice sorgente:

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