OT CLI コマンドの更新

GitHub でソースを表示

CLI コマンドは、openthread GitHub リポジトリ内の 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 を使用する例を追加します。少なくとも 1 つの例を含めてください。> プロンプトを含めないでください。また、標準の Done レスポンスを含む、返される完全な出力を必ず文書化してください。

    * @code
    * ba state
    * Started
    * Done
    * @endcode
   

CLI コマンドを使用すると、一般的な API メソッドと関数にコマンドラインからアクセスできるため、一部のコマンドの説明は対応する API と同じになります。コマンドの説明が同じ場合は、次の手順を完了します。

1. 関連する API を openthread/include/openthread ディレクトリで見つけます。たとえば、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 で始まる 1 つの連続したコメント ブロックでグループ化されます。複数の @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)

コマンドの説明

コマンドの説明を文書化するには、次の 3 つの方法があります。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 呼び出しとは異なります。また、netdata help のように、関連付けられた API がない場合もあります。別の説明を指定するには、@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 タグの下に文とマークダウン リストを入力します。

詳細を含むパラメータ

 * @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 プレフィックスをご覧ください。

マークダウン リストを含むパラメータ

@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 ブロックは、スペースを含まない連続した 1 つのコメントにする必要があります。@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 publish 接頭辞をご覧ください。

自動リンクの防止

Doxygen は、通常の単語（Joiner など）を CLI クラスへのリンクと間違えることがあります。文内で使用されているキーワードやクラス名に 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 ALIASES と特別なコマンドをサポートしています。

エイリアス	例	説明
@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 リファレンスへのリンクを作成します。
@overview	@overview	OpenThread CLI の概要へのリンクを作成します。
@netdata	@netdata	OT CLI を使用してネットワーク データを表示、管理するへのリンクを作成します。
@データセット	@データセット	OT CLI を使用してデータセットを表示、管理するへのリンクを作成します。
@udp	@udp	OT CLI を使用した UDP 機能のテストへのリンクを作成します。
@moreinfo	@moreinfo{@netdata}	紹介リンクを作成します。
@メモ	@note 重要なお知らせ。	メモのコールアウト ボックスを作成します。

make pretty スクリプトによって壊れた行を修正する

CLI パラメータやコマンド出力など、一部のコードコメントは、openthread.io リファレンスで正しくレンダリングされるように、1 行で記述する必要があります。ただし、make pretty には列幅の制限があるため、長い行でレンダリングされた出力が損なわれる可能性があります。

この状況は、以下の 2 つの例に示すように、改行を追加し、HTML コメントタグで囲むことで対処できます。

最初の例は、最大 6 つのパラメータを取る dns resolve コマンドです。make pretty チェックに合格しながら Doxygen を使用して構文を正しくレンダリングするには、パラメータをソース内で 3 行に分割する必要があります。

* @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}]

2 つ目の例は、history ipaddr list 5 コマンドの出力です。出力が適切にレンダリングされ、make pretty チェックに合格するには、5 つの出力行をそれぞれ次の 2 行に分割する必要があります。

* 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