Atualizar os comandos da CLI do OT

Veja o código-fonte no GitHub

Geramos comandos da CLI dos arquivos de origem da CLI na openthread (link em inglês) repositório do GitHub.

Este guia fornece instruções sobre como usar nossos comentários de Doxygen personalizados que usamos para criar a lista de comandos.

Primeiros passos

Para documentar um comando da CLI, conclua as etapas a seguir. É importante que siga essas etapas na ordem em que aparecem.

  1. Encontre o Cmd associado no openthread/src/cli diretório. Por exemplo, para encontrar ba state, pesquise Cmd("ba"). Cada comando terá um modelo de função associado:

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

  2. No modelo de função, localize a lógica de comando correta. Por exemplo, ba state:

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

  3. Antes da lógica começar, inicie o bloco Doxygen @cli:

    /**
 * @cli ba state

  4. Em seguida, logo abaixo de @cli, adicione exemplos usando @code. Incluir em um exemplo. Não inclua o comando > e lembre-se de documente o resultado completo do retorno, incluindo a resposta Done padrão.

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

Os comandos da CLI fornecem acesso de linha de comando a métodos comuns de API. e funções, alguns dos comandos compartilham a mesma descrição que seus a API correspondente. Se a descrição do comando for a mesma, conclua o etapas a seguir:

  1. Encontre a API associada no openthread/include/openthread diretório. Por exemplo, ba state é mapeado para otBorderAgentGetState.

  2. Use o comando api_copy e digite o nome da API diretamente abaixo dela. Antes da definição da API, use a cerquilha #. para criar a vinculação automática de Doxygen.

    @par api_copy
#otBorderAgentGetState

Aqui está um exemplo completo do número mínimo de comentários de Doxygen necessários para gerar automaticamente um comando da CLI OT:

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

Para revisar a saída HTML, consulte ba state. Para exemplos avançados e outras opções, consulte as seções a seguir.

Opções de modelo da CLI

Os comandos da CLI são agrupados por um bloco de comentários contínuos, começando com o Tag ALIAS @cli. Há suporte para vários exemplos de @code.

A ordem em que você especifica cada tag é importante.

  • @cparam precisa vir depois de @code
  • Se você estiver copiando uma descrição de API, @par api_copy precisará vir depois @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 seguir, saiba mais sobre como cada tag ALIAS é usada.

Nomes de comandos

Qualquer texto após @cli se torna o cabeçalho do nome do comando. Esse cabeçalho é usado a vinculação dinâmica, por exemplo, prefixo de publicação do netdata comando:

 * @cli netdata publish prefix

Outros comandos podem ser mais complexos. Por exemplo: O netdata publish dnssrp unicast oferece algumas opções:

  1. Publicar por endereço e número da porta
  2. Publicar pelo número da porta e pelo EID Mesh-Local de um dispositivo

Se um comando estiver sobrecarregado, use parênteses para identificar exclusivamente o comando.

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

Descrições de comandos

Há três maneiras de documentar as descrições de comandos. É possível copiar descrição da API, use a descrição da API, mas adicione mais informações, ou fornecer uma descrição completamente exclusiva que pertence somente ao comando da CLI. Nas próximas seções, vamos conhecer cada método.

Copiar a descrição correspondente da API

Use api_copy para copiar o método ou função de API correspondente. Quando você copiar APIs, certifique-se de que a descrição funcione para os e o comando da CLI. Evite usar frases que se aplicam apenas a função, por exemplo, This function ou This method. Prefere uma voz ativa, por exemplo, Gets the ou Sets the.

 * @par api_copy
 * #otBorderAgentGetState

Adicionar mais informações à descrição da API

Se você quiser usar api_copy, mas precisar adicionar outras informações que se aplica apenas ao comando da CLI, use @par. Depois da tag @par, verifique se para ir até a próxima linha.

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

Esses parágrafos são exibidos após a descrição da API.

Forneça apenas descrições específicas da CLI

Alguns comandos da CLI usam várias APIs ou são diferentes da chamada de API. Outros não têm uma API associada, por exemplo, netdata help. Para fornecer uma descrição separada, use @par. Não inclua um título @par e inicie sua descrição no próximo linha Nesse cenário, não use @api_copy.

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

Parâmetros

Defina os parâmetros de comando usando @cparam e @ca.

  • Coloque colchetes [ ] em torno dos argumentos opcionais.
  • Use barras verticais | (barras verticais) entre as opções de argumento.
  • Para mostrar detalhes do parâmetro, insira frases e listas de markdown abaixo da tag @cparam.

Parâmetros com detalhes

 * @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 a saída HTML, consulte prefixo de publicação do netdata.

Parâmetros com listas de markdown

Também é possível usar listas após @cparam. Isso é útil para quando você quiser fornecem detalhes sobre os argumentos de comando usados.

 * @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 a saída HTML, consulte netdata show.

Os blocos @cli precisam ser um comentário contínuo sem espaços. Se você adicionar em uma lista abaixo de @cparam e precisar de outro parágrafo abaixo dessa lista, use um ponto final . para encerrar a 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 mais exemplos, consulte a documentação Listas.

Você pode vincular outros métodos ou funções de API com #otFunctionName ou @sa. Insira esses links no final do bloco de comentários da 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
 */

Os links @sa são exibidos no título Referências da CLI e da API. Para revisar o HTML a saída, consulte prefixo de publicação do netdata.

Às vezes, o Doxygen pode confundir uma palavra normal com um link para uma classe de CLI, por exemplo, a palavra Joiner. Para evitar que o Doxygen se vincule a palavras-chave ou classes usados em uma frase, use o operador % na frente da palavra, Por exemplo:

Clear the %Joiner discerner

Para mais informações, consulte Geração automática de vinculações no guia de doxigênio.

Use @csa para vincular a outros comandos.

* @csa{netdata publish dnssrp anycast}

Se um comando estiver sobrecarregado, inclua os parênteses e adicione uma vírgula. se aplicável. Não use espaços entre parênteses:

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

Comandos especiais do Doxygen

Os comandos da CLI são compatíveis com os seguintes ALIASES e comandos especiais do Doxygen:

ALIAS Exemplo Descrição
@cli @cli ba port Nome do comando. Inicia um bloco de comentários da CLI.
@código @code
ba porta
41953
Concluído
@endcode		 Exemplo de comando.
@ca [@ca{prefixo}] Argumento de comando. Use colchetes [ ] para argumentos opcionais.
@cparam @cparam joiner discerner @ca{discerner}
Detalhes do parâmetro.		 Parâmetros de comando.
@par @par
Descrição da CLI opcional.		 Parágrafos específicos da CLI.
@csa @csa{prefix add} Command Consulte também. Links para outro comando.
@sa @sa otBorderRouterConfig Consulte também. Cria um link para uma referência da API.
@visão geral @visão geral Cria um link para a Visão geral da CLI OpenThread.
@netdata @netdata Cria um link para Exibir e gerenciar dados de rede com a CLI OT.
@dataset @dataset Cria um link para Exibir e gerenciar conjuntos de dados com a CLI OT.
@udp @udp Cria um link para Testar a funcionalidade UDP com a CLI OT.
@moreinfo @moreinfo{@netdata} Cria um link de referência.
@nota @note Frase de destaque importante. Cria uma caixa de frase de destaque de nota.

Como corrigir linhas corrompidas pelo script make pretty

Alguns comentários de código, como parâmetros da CLI ou resposta ao comando, precisam estar no uma única linha para que sejam renderizados corretamente na referência openthread.io. No entanto, make pretty impõe um limite de largura de coluna, que pode quebrar a de saída para linhas longas.

Essa situação pode ser resolvida adicionando quebras de linha e colocando-as com uma tag de comentário HTML, como mostrado nos dois exemplos abaixo.

O primeiro exemplo é o comando dns resolve, que pode levar até seis parâmetros. Para renderizar corretamente a sintaxe usando Doxygen e ainda transmitir na verificação make pretty, os parâmetros precisam ser divididos em três linhas na origem:

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

O segundo exemplo é a saída do comando history ipaddr list 5. Para que a saída seja renderizada corretamente e ainda transmita a verificação make pretty, cada uma das cinco linhas de saída precisa ser dividida em duas, da seguinte maneira:

* 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