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 を使用して例を追加します。含める 少なくとも 1 つの例が必要です> プロンプトは含めないでください。また、次のことを確認します。 標準の 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 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 公開プレフィックス command:

 * @cli netdata publish prefix

</ph>

より複雑なコマンドもあります。たとえば netdata publish dnssrp unicast には、次のオプションがあります。

1. アドレスとポート番号に基づいて公開
2. ポート番号とデバイスのメッシュローカル EID を指定して公開する

コマンドが過負荷になっている場合は、かっこを使用してコマンドを一意に識別してください。

 * @cli netdata publish dnssrp unicast (mle)
 * @cli netdata publish dnssrp unicast (addr,port)

コマンドの説明

コマンドの説明を文書化する方法は 3 つあります。この API の説明。API の説明を使用し、追加情報を追加します。 元の広告のみに属す完全に独自の説明を 使用できます。以降のセクションでは、それぞれの方法について説明します。

対応する 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 タグの下。

詳細を含むパラメータ

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

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

@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 を自動的にリンクする

他の 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
 */

[CLI と API リファレンス] の見出しに @sa リンクが表示されます。HTML を確認するには 出力については、このモジュールの netdata 公開接頭辞。

自動リンクを無効にする

場合によっては、Doxygen は通常の単語を、 たとえば、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 と特別なコマンドをサポートしています。

make pretty スクリプトによって中断される行を修正する

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

この状況に対処するには、改行を追加します。 次の 2 つの例のように HTML コメントタグを追加します。

最初の例は dns resolve コマンドです。このコマンドは最大 6 回 あります。Doxygen を使用して構文を正しくレンダリングしながらも、 make pretty チェックの場合、パラメータは 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