更新 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 狀態。如需進階範例和其他選項，請參閱以下各節。

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 publish 前置字串指令：

 * @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，例如 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 發布前置字串。

包含 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 發布前置字串。

有時候，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 @code
ba 通訊埠
41953
完成
@endcode		 指令範例。
@ca [@ca{prefix}] 指令引數。使用括號 [ ] 做為選用引數。
@cparam @cparam 彙整工具 @ca{discerner}
參數詳細資料。		 指令參數。
@par @par
選填的 CLI 說明。		 CLI 專屬段落。
@csa @csa{prefix add} 指令也另行參閱。其他指令的連結。
@sa @sa otBorderRouterConfig 另請參閱。建立 API 參考資料連結。
@overview @overview 建立 OpenThread CLI 總覽的連結。
@netdata @netdata 建立透過 OT CLI 顯示及管理網路資料的連結。
@資料集 @資料集 建立透過 OT CLI 顯示及管理資料集的連結。
@udp @udp 建立使用 OT CLI 測試 UDP 功能的連結。
@moreinfo @moreinfo{@netdata} 建立推薦連結。
@note @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