更新 OT CLI 指令

前往 GitHub 查看原始碼

我們會產生 CLI 指令 建立 Deployment 資訊清單 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

以下是 Doxygen 最低品質要求的完整範例 自動產生 OT CLI 指令

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

如要查看 HTML 輸出內容，請參閱 Ba 狀態。 如需進階範例和其他選項，請參閱下列各節。

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-本機 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 定義指令參數。

  • 在選用引數前後加上方括號 [ ]。
  • 在引數選項之間使用直立線 | (直立線)。
  • 如要顯示參數詳細資料，您可以輸入句子和 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 的 清單。

如要連結至其他 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 參考資料」標題中。檢查 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 符號 @code
ba 通訊埠
41953
完成
@endcode		 指令範例。
@ca [@ca{prefix}] 指令引數。您可以使用方括號 [ ] 做為選用引數。
@cparam @cparam 彙整器 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 指令，最多可能需要六個時間 參數。如要在 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