Actualizar comandos de la CLI de OT

Ver código fuente en GitHub

Generamos comandos de la CLI desde los archivos de origen de la CLI en la openthread Repositorio de GitHub.

En esta guía, se proporcionan instrucciones para usar nuestros comentarios personalizados de Doxygen que usamos para crear la lista de comandos.

Comenzar

Para documentar un comando de la CLI, completa los siguientes pasos. Es importante que sigas estos pasos en el orden indicado.

1. Busca el Cmd asociado en openthread/src/cli . Por ejemplo, para encontrar ba state, busca Cmd("ba"). Cada comando tendrá una plantilla de función asociada:

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

2. En la plantilla de funciones, ubica la lógica de comando correcta. Por ejemplo, ba state:

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

3. Antes de que comience la lógica, inicia el bloque de Doxygen @cli:

   /**
    * @cli ba state
   

4. A continuación, justo debajo de @cli, agrega ejemplos con @code. Incluir en al menos un ejemplo. No incluyas el mensaje > y asegúrate de Documenta el resultado que se muestra completo, incluida la respuesta Done estándar.

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

Debido a que los comandos de la CLI proporcionan acceso de línea de comandos a los métodos comunes de la API y funciones, algunos de los comandos comparten la misma descripción que sus la API correspondiente. Si la descripción del comando es la misma, completa los siguientes pasos:

1. Busca la API asociada en openthread/include/openthread. . Por ejemplo, ba state se asigna a otBorderAgentGetState.

2. Usa el comando api_copy y, luego, ingresa el nombre de la API directamente debajo de este. Frente a la definición de la API, asegúrate de usar el signo numeral #. para crear el vínculo automático de Doxygen.

   @par api_copy
   #otBorderAgentGetState
   

Este es un ejemplo completo de los comentarios mínimos de Doxígeno necesarios para generar automáticamente un comando de OT CLI:

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

Para revisar el resultado HTML, consulta ba state: Para ver ejemplos avanzados y opciones adicionales, consulta las siguientes secciones.

Opciones de plantillas de CLI

Los comandos de la CLI se agrupan por un bloque de comentarios continuos, que comienza con Etiqueta de ALIAS @cli. Se admiten varios ejemplos de @code.

El orden en que especificas cada etiqueta es importante.

• El valor de @cparam debe ser posterior al @code
• Si copias una descripción de una API, @par api_copy debe aparecer despué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

A continuación, obtén más información sobre cómo se usa cada etiqueta ALIAS.

Nombres de comandos

Cualquier texto después de @cli se convierte en el encabezado del nombre del comando. Este encabezado se utiliza en la vinculación dinámica, por ejemplo, Prefijo de publicación de netdata :

 * @cli netdata publish prefix

Es posible que otros comandos sean más complejos. Por ejemplo: netdata publish dnssrp unicast ofrece algunas opciones:

1. Publicar por dirección y número de puerto
2. Publicar por número de puerto y EID local de malla de un dispositivo

Si un comando está sobrecargado, usa paréntesis para identificarlo de forma única.

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

Descripciones de comandos

Hay tres formas de documentar las descripciones de los comandos. Puedes copiar el descripción de la API, usar la descripción de la API, pero agregar información adicional, o proporciona una descripción completamente única que pertenezca solo al Comando de la CLI. En las siguientes secciones, revisaremos cada método.

Copia la descripción de la API correspondiente

Usa api_copy para copiar la función o el método de la API correspondiente. Cuándo copia las APIs, asegúrate de que la descripción funcione tanto para API y el comando de la CLI. Evita usar frases que se apliquen solo a un por ejemplo, This function o This method. Preferencias una voz activa, por ejemplo Gets the o Sets the

 * @par api_copy
 * #otBorderAgentGetState

Agrega más información a la descripción de la API

Si deseas utilizar api_copy, pero necesitas agregar información adicional que solo se aplica al comando de la CLI, usa @par. Después de la etiqueta @par, asegúrate de que para ir a la línea siguiente.

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

Estos párrafos se muestran después de la descripción de la API.

Proporciona solo descripciones específicas de la CLI

Algunos comandos de la CLI usan varias APIs o difieren de la llamada a la API. Otros no tienen una API asociada, por ejemplo, netdata help. Para proporcionar una descripción independiente, usa @par. No incluyas un título en @par y empieza la descripción a partir de la siguiente línea. En este caso, no uses @api_copy.

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

Parámetros

Define parámetros de comando con @cparam y @ca.

• Coloca corchetes [ ] alrededor de los argumentos opcionales.
• Usa barras verticales | (barras verticales) entre las opciones de argumentos.
• Para mostrar los detalles de los parámetros, puedes ingresar oraciones y listas de Markdown debajo de la etiqueta @cparam.

Parámetros con detalles

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

Para revisar el resultado de HTML, consulta el prefijo de publicación de netdata.

Parámetros con listas de Markdown

También puedes usar listas posteriores al @cparam. Esto es útil cuando quieres proporcionan detalles sobre los argumentos del comando que se usan.

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

Para revisar el resultado de HTML, consulta netdata show.

Los bloques @cli deben ser un comentario continuo sin espacios. Si agregas una lista debajo de @cparam y, luego, necesitas otro párrafo debajo de esa lista, usa un punto . para finalizar la lista manualmente

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

Para ver más ejemplos, consulta el Listas.

Vincular APIs automáticamente

Puedes vincular otros métodos o funciones de la API con #otFunctionName. @sa Ingresa estos vínculos al final del bloque de comentarios 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
 */

Se muestran los vínculos de @sa en el encabezado Referencias de la CLI y la API. Para revisar el código HTML, sigue estos pasos: salida, consulta prefijo de publicación de netdata.

Cómo evitar los vínculos automáticos

A veces, Doxygen puede confundir una palabra normal con un vínculo a una clase de CLI, por Por ejemplo, la palabra Joiner. Para evitar que Doxígeno vincule a palabras clave o clases nombres usados en una oración, usa el operador % delante de la palabra, por ejemplo:

Clear the %Joiner discerner

Para obtener más información, consulta Generación automática de vínculos en la guía de Doxígeno.

Vincular automáticamente a otros comandos

Usa @csa para vincular otros comandos.

* @csa{netdata publish dnssrp anycast}

Si un comando está sobrecargado, incluye los paréntesis y agrega una coma. si corresponde. No uses espacios dentro de los paréntesis:

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

Comandos especiales de Doxygen

Los comandos de la CLI admiten las siguientes ALIASES de Doxygen y los comandos especiales:

Repara las líneas rotas por la secuencia de comandos make pretty

Algunos comentarios de código, como los parámetros de la CLI o el resultado del comando, deben estar activados una sola línea para que se rendericen correctamente en la referencia openthread.io. Sin embargo, make pretty impone un límite de ancho de columna, que puede romper el para líneas largas.

Para solucionar esta situación, se pueden agregar saltos de línea y delimitarlos con una etiqueta de comentario HTML, como se muestra en los siguientes dos ejemplos.

El primer ejemplo es el comando dns resolve, que puede tardar hasta seis parámetros. Para renderizar correctamente la sintaxis con Doxygen y, al mismo tiempo, pasar la verificación make pretty, los parámetros deben dividirse en tres líneas en la fuente:

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

El segundo ejemplo es el resultado del comando history ipaddr list 5. Para que el resultado se procese correctamente y pase la verificación de make pretty, haz lo siguiente: cada una de las cinco líneas de resultado debe dividirse en dos líneas, de la siguiente manera:

* 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