Atualizar os comandos da CLI do OT

Consulte o código-fonte no GitHub

Geramos comandos da CLI com base nos arquivos de origem da CLI no repositório do GitHub openthread.

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

Primeiros passos

Para documentar um comando da CLI, conclua as etapas a seguir. É importante seguir essas etapas na ordem apresentada.

  1. Encontre o Cmd associado no diretório openthread/src/cli. 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 de a lógica começar, inicie o bloco Doxygen @cli:

    /**
 * @cli ba state

  4. Em seguida, logo abaixo de @cli, adicione exemplos usando @code. Inclua pelo menos um exemplo. Não inclua a solicitação > e certifique-se de documentar a saída de retorno completa, incluindo a resposta Done padrão.

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

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

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

  2. Use o comando api_copy e insira o nome da API logo abaixo dele. Na frente da definição da API, use o sinal de libra # para criar o link Doxygen automático.

    @par api_copy
#otBorderAgentGetState

Confira um exemplo completo de comentários mínimos do 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 (em inglês). Para exemplos avançados e opções adicionais, 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 a 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 da API, @par api_copy precisará vir depois 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 seguir, saiba mais sobre como cada tag ALIAS é usada.

Nomes de comando

Qualquer texto após @cli se torna o cabeçalho do nome do comando. Esse cabeçalho é usado na vinculação dinâmica, por exemplo, no comando netdata publish prefix:

 * @cli netdata publish prefix

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

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

Se um comando estiver sobrecarregado, use parênteses para identificá-lo de maneira exclusiva.

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

Descrições de comandos

Há três maneiras de documentar descrições de comandos. É possível copiar a descrição da API, usá-la, mas adicionar outras informações, ou fornecer uma descrição completamente exclusiva que pertença apenas ao comando da CLI. Abordaremos cada método nas próximas seções.

Copie a descrição da API correspondente

Use api_copy para copiar o método ou a função da API correspondente. Ao copiar APIs, verifique se a descrição funcionará para a API e o comando da CLI. Evite usar frases que se apliquem apenas a uma função, como This function ou This method. Prefira 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 aplicam apenas ao comando da CLI, use @par. Após a tag @par, vá 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 para a CLI

Alguns comandos da CLI usam várias APIs ou são diferentes da chamada de API. Outras 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 comece sua descrição na próxima linha. Nessa situação, 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 os argumentos opcionais entre colchetes [ ].
  • Use barras verticais | (barras verticais) entre as opções de argumentos.
  • Para exibir detalhes dos parâmetros, 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 quando você quer fornecer 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 de @cli precisam ser um comentário contínuo sem espaços. Se você adicionar uma lista abaixo de @cparam e precisar de outro parágrafo abaixo dela, use um ponto . 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 ver mais exemplos, consulte as Listas do Doxygen.

É possível vincular a outros métodos ou funções da 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 mostrados no título Referências da CLI e da API. Para revisar a saída HTML, consulte o prefixo de publicação do netdata.

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

Clear the %Joiner discerner

Para ver mais informações, consulte Geração automática de links no guia Doxygen.

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 do Doxygen e comandos especiais:

ALIAS Exemplo Descrição
@cli Porta ba @cli Nome do comando. Inicia um bloco de comentários da CLI.
@código @code
porta ba
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} Comando Consulte também. Direciona 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 do OpenThread.
@netdata @netdata Cria um link para Mostrar e gerenciar dados da rede com a CLI OT.
@conjunto de dados @conjunto de dados Cria um link para Mostrar 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 texto explicativo.

Como corrigir linhas corrompidas pelo script make pretty

Alguns comentários do código, como parâmetros da CLI ou saída de comando, precisam estar em 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, o que pode interromper a saída renderizada para linhas longas.

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

O primeiro exemplo é o comando dns resolve, que pode usar até seis parâmetros. Para renderizar corretamente a sintaxe usando Doxygen e ainda passar a 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 passe na verificação de make pretty, cada uma das cinco linhas de saída precisa ser dividida em duas linhas, 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