更新 OT CLI 命令

<ph type="x-smartling-placeholder"></ph> 在 GitHub 上查看源代码

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

本指南介绍了如何使用我们的自定义 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 命令：

/**
 * @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 发布前缀 命令：

 * @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 说明，但要添加其他信息 或提供完全独特的说明， 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 定义命令参数。

  • 在可选参数两边加上英文括号 [ ]。
  • 在参数选项之间使用竖线 |（竖线）。
  • 如需显示参数详细信息，您可以输入句子和 Markdown 列表 在 @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 发布前缀。

带 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。在 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 发布前缀。

有时，Doxygen 可能会将某个常规字词误认为是指向 CLI 类的链接， 例如 Joiner 一词。为了阻止 Doxygen 链接到关键字或类别 在句子前面使用 % 运算符， 例如：

Clear the %Joiner discerner

如需了解详情，请参阅 自动生成链接 。

使用 @csa 链接到其他命令。

* @csa{netdata publish dnssrp anycast}

如果命令超载，请添加括号并添加英文逗号 （如果适用）。请勿在括号内使用空格：

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

Doxygen 特殊命令

CLI 命令支持以下 Doxygen ALIASES 和特殊命令：

别名 示例 说明
@cli @cli ba 端口 命令名称。启动 CLI 注释块。
@代码 @code
ba 端口
41953
完成
@endcode		 命令示例。
@ca [@ca{prefix}] 命令参数。为可选参数使用括号 [ ]。
@cparam @cparam joiner discerner @ca{discerner}
参数详细信息。		 命令参数。
标准杆 @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