我們會從 openthread GitHub 存放區的 CLI 來源檔案產生 CLI 指令。
本指南說明如何使用我們自訂 Doxygen 註解來建立指令清單。
立即開始
如要記錄 CLI 指令,請完成下列步驟。請務必依照提供的順序執行下列步驟。
從
openthread/src/cli
目錄找出相關聯的Cmd
。舉例來說,如要尋找ba state
,請搜尋Cmd("ba")
。每個指令都會有相關聯的函式範本:template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])
在函式範本中找出正確的指令邏輯。例如
ba state
:else if (aArgs[0] == "state")
在邏輯開始之前,啟動
@cli
Doxygen 區塊:/** * @cli ba state
接下來,緊接在
@cli
下方,使用@code
新增範例。至少須提供一個範例。請勿加入>
提示,並務必記錄完整的傳回輸出內容,包括標準Done
回應。* @code * ba state * Started * Done * @endcode
由於 CLI 指令可讓您透過指令列存取常見的 API 方法和函式,因此有些指令的說明內容與對應的 API 相同。如果指令說明相同,請完成下列步驟:
從
openthread/include/openthread
目錄中找出相關聯的 API。例如,ba state
對應至otBorderAgentGetState
。使用
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
提供以下幾種選項:
- 依位址和通訊埠號碼發布
- 依通訊埠編號和裝置的網格本機 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 的清單。
自動連結 API
您可以使用 #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