Обновление команд OT CLI

Посмотреть исходный код на GitHub

Мы генерируем команды CLI из исходных файлов CLI в репозитории openthread GitHub.

В этом руководстве представлены инструкции по использованию наших пользовательских комментариев Doxygen, которые мы используем для создания списка команд.

Начать

Чтобы документировать команду CLI, выполните следующие шаги. Важно выполнить эти шаги в указанном порядке.

  1. Найдите соответствующий Cmd в каталоге openthread/src/cli . Например, чтобы найти ba state , найдите Cmd("ba") . Каждая команда будет иметь связанный шаблон функции:

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

  2. В шаблоне функции найдите правильную логику команды. Например, ba state :

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

  3. Прежде чем начнется логика, запустите блок @cli Doxygen:

    /**
 * @cli ba state

  4. Далее, сразу под @cli , добавьте примеры, используя @code . Включите хотя бы один пример. Не включайте приглашение > и обязательно задокументируйте полный возвращаемый результат, включая стандартный ответ Done .

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

Поскольку команды CLI предоставляют доступ к общим методам и функциям API из командной строки, некоторые команды имеют то же описание, что и соответствующий API. Если описание команды такое же, выполните следующие действия:

  1. Найдите соответствующий API в каталоге openthread/include/openthread . Например, ba state сопоставляется с otBorderAgentGetState .

  2. Используйте команду api_copy , затем введите имя API прямо под ней. Перед определением API обязательно используйте знак решетки # , чтобы создать автоматическую ссылку Doxygen.

    @par api_copy
#otBorderAgentGetState

Вот полный пример минимальных комментариев Doxygen, необходимых для автоматического создания команды OT CLI:

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

Чтобы просмотреть вывод HTML, обратитесь к bastate . Дополнительные примеры и дополнительные параметры см. в следующих разделах.

Параметры шаблона CLI

Команды CLI сгруппированы в один непрерывный блок комментариев, начинающийся с тега ALIAS @cli . Поддерживается несколько примеров @code .

Порядок, в котором вы указываете каждый тег, важен.

  • @cparam должен идти после @code
  • Если вы копируете описание API, @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

Далее узнайте больше о том, как используется каждый тег ALIAS.

Имена команд

Любой текст после @cli становится заголовком имени команды. Этот заголовок используется при динамическом связывании, например, в команде префикса публикации netdata :

 * @cli netdata publish prefix

Другие команды могут быть более сложными. Например, netdata publish dnssrp unicast предоставляет несколько опций:

  1. Публикация по адресу и номеру порта
  2. Публикация по номеру порта и Mesh-Local EID устройства.

Если команда перегружена, используйте круглые скобки, чтобы однозначно идентифицировать команду.

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

Описание команд

Существует три способа документирования описаний команд. Вы можете скопировать описание API, использовать описание API, но добавить дополнительную информацию, или предоставить совершенно уникальное описание, принадлежащее только команде CLI. В следующих разделах мы рассмотрим каждый метод.

Скопируйте соответствующее описание API

Используйте api_copy , чтобы скопировать соответствующий метод или функцию API. При копировании API убедитесь, что описание подходит как для API, так и для команды CLI. Избегайте использования фраз, относящихся только к функции, например This function или This method . Предпочитайте активный залог, например Gets the или Sets the . 

 * @par api_copy
 * #otBorderAgentGetState

Добавьте дополнительную информацию в описание API

Если вы хотите использовать api_copy , но вам нужно добавить дополнительную информацию, применимую только к команде CLI, используйте @par . После тега @par обязательно перейдите на следующую строку. 

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

Эти абзацы отображаются после описания API.

Предоставляйте только описания, специфичные для CLI.

Некоторые команды CLI используют несколько API или отличаются от вызова API. Другие не имеют связанного API, например, netdata help . Чтобы предоставить отдельное описание, используйте @par . Не включайте заголовок @par и начните описание со следующей строки. В этом случае не используйте @api_copy . 

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

Параметры

Определите параметры команды, используя @cparam и @ca .

  • Заключите необязательные аргументы в скобки [ ] .
  • Используйте вертикальные полосы | (трубы) между вариантами аргументов.
  • Чтобы отобразить подробную информацию о параметрах, вы можете ввести предложения и списки уценок под тегом @cparam .

Параметры с подробностями 

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

Чтобы просмотреть вывод HTML, обратитесь к префиксу публикации netdata .

Параметры со списками уценок

Вы также можете использовать списки после @cparam . Это полезно, если вы хотите предоставить подробную информацию об используемых аргументах команды. 

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

Чтобы просмотреть вывод HTML, обратитесь к netdata show .

Блоки @cli должны представлять собой один непрерывный комментарий без пробелов. Если вы добавляете список под @cparam , а затем вам нужен еще один абзац под этим списком, используйте точку . чтобы вручную завершить список. 

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

Дополнительные примеры см. в списках Doxygen.

Вы можете ссылаться на другие методы или функции API с помощью #otFunctionName или @sa . Введите эти ссылки в конце блока комментариев 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
 */

Ссылки @sa отображаются в заголовках CLI и API References . Чтобы просмотреть вывод HTML, обратитесь к префиксу публикации netdata .

Иногда Doxygen может принять обычное слово за ссылку на класс CLI, например, слово Joiner . Чтобы запретить Doxygen ссылаться на ключевые слова или имена классов, используемые в предложении, используйте оператор % перед словом, например: 

Clear the %Joiner discerner

Для получения дополнительной информации обратитесь к разделу «Автоматическое создание ссылок» в руководстве Doxygen.

Используйте @csa для связи с другими командами. 

* @csa{netdata publish dnssrp anycast}

Если команда перегружена, включите круглые скобки и добавьте запятую, если применимо. Не используйте пробелы внутри круглых скобок: 

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

Специальные команды Doxygen

Команды CLI поддерживают следующие псевдонимы и специальные команды Doxygen:

Псевдоним Пример Описание
@cli @cli ба порт Имя команды. Запускает блок комментариев CLI.
@код @код
порт Ба
41953
Сделанный
@endcode		 Пример команды.
@ca [@ca{префикс}] Аргумент команды. Используйте скобки [ ] для необязательных аргументов.
@cпарам @cparam joiner проницатель @ca{discerner}
Детали параметра.		 Параметры команды.
@пар @пар
Необязательное описание CLI.		 Специальные параграфы CLI.
@csa @csa{добавление префикса} Команда См. также. Ссылки на другую команду.
@са @sa otBorderRouterConfig См. также. Создает ссылку на ссылку API.
@обзор @обзор Создает ссылку на обзор OpenThread CLI .
@netdata @netdata Создает ссылку на отображение и управление сетевыми данными с помощью OT CLI .
@dataset @dataset Создает ссылку на отображение и управление наборами данных с помощью OT CLI .
@udp @udp Создает ссылку на проверку функциональности UDP с помощью OT CLI .
@moreinfo @moreinfo{@netdata} Создает реферальную ссылку.
@примечание @note Важное замечание. Создает поле выноски примечания.

Исправление строк, поврежденных скриптом make pretty

Некоторые комментарии к коду, такие как параметры CLI или выходные данные команды, должны быть в одной строке, чтобы они правильно отображались в ссылке openthread.io. Однако make pretty накладывает ограничение на ширину столбца, что может нарушить визуализируемый вывод для длинных строк.

Эту ситуацию можно решить, добавив разрывы строк и заключив их в тег комментария HTML, как показано в двух примерах ниже.

Первый пример — команда dns resolve , которая может принимать до шести параметров. Чтобы правильно отобразить синтаксис с помощью Doxygen и при этом пройти проверку make pretty , параметры необходимо разделить на три строки в исходном коде: 

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

Второй пример — это выходные данные команды history ipaddr list 5 . Чтобы выходные данные отображались правильно и по-прежнему проходили проверку make pretty , каждую из пяти выходных строк необходимо разделить на две строки следующим образом: 

* 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