Actualizar comandos de la CLI de OT

Ver el código fuente en GitHub

Generamos comandos de la CLI desde los archivos fuente de la CLI en el repositorio openthread de GitHub.

En esta guía, se proporcionan instrucciones sobre cómo usar nuestros comentarios personalizados de Doxygen 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 el directorio 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 función, busca 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 @cli de Doxygen:

    /**
 * @cli ba state

  4. A continuación, justo debajo de @cli, agrega ejemplos con @code. Incluye al menos un ejemplo. No incluyas el mensaje > y asegúrate de documentar el resultado completo que se muestra, 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 funciones y métodos de API comunes, algunos de ellos comparten la misma descripción que su API correspondiente. Si la descripción del comando es la misma, completa los siguientes pasos:

  1. Busca la API asociada en el directorio 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

A continuación, se incluye un ejemplo completo de los comentarios de Doxygen mínimos 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 de HTML, consulta estado ba. 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 continuo, que comienza con la etiqueta @cli de ALIAS. Se admiten varios ejemplos de @code.

El orden que especifiques para cada etiqueta es importante.

  • @cparam debe ser posterior a @code
  • Si copias la descripción de una API, @par api_copy debe ir después de @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 usa en los vínculos dinámicos, por ejemplo, el comando de prefijo de netdata publish:

 * @cli netdata publish prefix

Otros comandos podrían ser más complejos. Por ejemplo, netdata publish dnssrp unicast ofrece algunas opciones:

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

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

Existen tres maneras de documentar las descripciones de los comandos. Puedes copiar la descripción de la API, usarla, pero agregar información adicional o proporcionar una descripción ú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 el método o la función de la API correspondiente. Cuando copies las APIs, asegúrate de que la descripción funcionará para la API y el comando de la CLI. Evita usar frases que se apliquen solo a una función, como This function o This method. Prefiere una voz activa, por ejemplo, Gets the o Sets the.

 * @par api_copy
 * #otBorderAgentGetState

Cómo agregar más información a la descripción de la API

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

 * @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, como netdata help. Para proporcionar una descripción aparte, usa @par. No incluyas un título @par y comienza la descripción en 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 los parámetros de comando con @cparam y @ca.

  • Coloca corchetes [ ] entre los argumentos opcionales.
  • Usa barras verticales | (barras verticales) entre las opciones de argumento.
  • 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 en HTML, consulta el prefijo de netdata publish.

Parámetros con listas de Markdown

También puedes usar listas después del @cparam. Esto es útil cuando deseas proporcionar 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 en formato HTML, consulta netdata show.

@cli bloques 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 de forma manual.

* @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 obtener más ejemplos, consulta las listas de Doxygen.

Puedes vincular otros métodos o funciones de API con #otFunctionName o @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
 */

Los vínculos @sa se muestran en el encabezado Referencias de la CLI y la API. Para revisar el resultado de HTML, consulta el prefijo de publicación de netdata.

A veces, Doxygen puede confundir una palabra normal con un vínculo a una clase de CLI, por ejemplo, la palabra Joiner. Para evitar que Doxygen se vincule a palabras clave o nombres de clase 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 Doxygen.

Usa @csa para establecer vínculos a 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 entre 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 comandos especiales:

ALIAS Ejemplo Descripción
@CLI Puerto @cli Ba Nombre del comando. Inicia un bloque de comentarios de la CLI.
@código @code
ba port
41953
Listo
@endcode		 Ejemplo de comando
@ca [@ca{prefix}] Argumento de comando. Usa corchetes [ ] para los argumentos opcionales.
@cparam @cparam joiner discerner @ca{discerner}
Detalles del parámetro.		 Parámetros de comando
@par @par
Descripción opcional de la CLI.		 párrafos específicos de la CLI.
@csa @csa{prefix add} Consulta también el comando. Se vincula a otro comando.
@sa @sa otBorderRouterConfig Consulta también. Crea un vínculo a una referencia de la API.
@descripción general @descripción general Crea un vínculo a la Descripción general de la CLI de OpenThread.
@netdatos @netdatos Crea un vínculo para mostrar y administrar datos de red con OT CLI.
@conjunto de datos @conjunto de datos Crea un vínculo para Mostrar y administrar conjuntos de datos con OT CLI.
@udp @udp Crea un vínculo para probar la funcionalidad de UDP con OT CLI.
@másinformación @moreinfo{@netdata} Crea un vínculo de referencia.
@nota @note: Texto destacado importante. Crea un cuadro de texto destacado de notas.

Se corrigieron 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 en una sola línea para que se rendericen correctamente en la referencia de openthread.io. Sin embargo, make pretty impone un límite de ancho de columna, lo que puede interrumpir el resultado renderizado para líneas largas.

Para solucionar esta situación, debes agregar saltos de línea y encerrarlos con una etiqueta de comentario HTML, como se muestra en dos ejemplos a continuación.

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

* @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 renderice correctamente y aún apruebe la verificación de make pretty, cada una de las cinco líneas del 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