更新 OT CLI 命令

查看 GitHub 上的源代码

我们根据 openthread GitHub 代码库中的 CLI 源文件生成 CLI 命令。

本指南介绍了如何使用我们用于创建命令列表的自定义 Doxygen 注释。

开始使用

如需记录 CLI 命令，请完成以下步骤。请务必按照提供的顺序执行以下步骤。

  1. 从 openthread/src/cli 目录中查找关联的 Cmd。例如，如需查找 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. 从 openthread/include/openthread 目录中查找关联的 API。例如，ba state 映射到 otBorderAgentGetState。

  2. 使用 api_copy 命令，然后直接在其下方输入 API 名称。在 API 定义前面，请务必使用井号 # 创建自动 Doxygen 链接。

    @par api_copy
#otBorderAgentGetState

以下是自动生成 OT CLI 命令所需的最少 Doxygen 注释的完整示例：

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

如需查看 HTML 输出，请参阅 ba state。如需查看高级示例和其他选项，请参阅以下部分。

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 publishprefix 命令：

 * @cli netdata publish prefix

其他命令可能更复杂。例如，netdata publish dnssrp unicast 提供了几个选项：

  1. 按地址和端口号发布
  2. 按端口号和设备的网状网本地 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 没有关联的 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 标记下方输入句子和 Markdown 列表。

包含详情的参数

 * @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 publish 前缀。

带 Markdown 列表的参数

您还可以在 @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 的列表。

您可以使用 #otFunctionName 或 @sa 链接到其他 API 方法或函数。在 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 参考文档标题中。如需查看 HTML 输出，请参阅 netdata publish 前缀。

有时，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 ba 端口 命令名称。启动 CLI 注释块。
@代码 @code
ba 端口
41953
完成
@endcode		 命令示例。
@ca [@ca{prefix}] 命令参数。为可选参数使用括号 [ ]。
@cparam @cparamjoiner discerner @ca{discerner}
参数详细信息。		 命令参数。
@par @par
可选 CLI 说明。		 CLI 专用段落。
@csa @csa{prefix add} 命令另请参阅。指向其他命令的链接。
@sa @sa otBorderRouterConfig 另请参阅。创建指向 API 参考文档的链接。
@概览 @概览 创建指向 OpenThread CLI 概览的链接。
@netdata @netdata 创建指向使用 OT CLI 显示和管理网络数据的链接。
@dataset @dataset 创建一个指向使用 OT CLI 显示和管理数据集的链接。
@udp @udp 创建指向使用 OT CLI 测试 UDP 功能的链接。
@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