OT-CLI-Befehle aktualisieren

<ph type="x-smartling-placeholder"></ph> Quelle auf GitHub ansehen

Wir generieren CLI-Befehle aus den CLI-Quelldateien im Openthread GitHub-Repository

Dieser Leitfaden enthält Anweisungen zur Verwendung unserer benutzerdefinierten Doxygen-Kommentare mit dem wir die Befehlsliste erstellen.

Erste Schritte

Führen Sie die folgenden Schritte aus, um einen CLI-Befehl zu dokumentieren. Es ist wichtig, führen Sie diese Schritte in der angegebenen Reihenfolge aus.

1. Die zugehörige Cmd findest du in der openthread/src/cli -Verzeichnis. Wenn Sie beispielsweise nach „ba state“ suchen, geben Sie „Cmd("ba")“ ein. Jedem Befehl ist eine Funktionsvorlage zugeordnet:

   template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])
   

2. Suchen Sie in der Funktionsvorlage nach der richtigen Befehlslogik. Zum Beispiel ba state:

   else if (aArgs[0] == "state")
   

3. Bevor die Logik beginnt, starten Sie den Doxygen-Block @cli:

   /**
    * @cli ba state
   

4. Fügen Sie als Nächstes direkt unter @cli Beispiele mit @code hinzu. Einschließen bei mindestens ein Beispiel. Fügen Sie nicht die >-Aufforderung ein und achten Sie darauf, Dokumentieren Sie die vollständige Rückgabeausgabe, einschließlich der Standardantwort Done.

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

Da CLI-Befehle einen Befehlszeilenzugriff auf gängige API-Methoden bieten und Funktionen verwenden, haben einige Befehle dieselbe Beschreibung wie die der entsprechenden API. Wenn die Befehlsbeschreibung identisch ist, füllen Sie das Feld folgenden Schritten:

1. Zugehörige API in openthread/include/openthread suchen -Verzeichnis. Beispielsweise ist ba state der otBorderAgentGetState zugeordnet.

2. Verwenden Sie den Befehl api_copy und geben Sie dann den API-Namen direkt darunter ein. Verwenden Sie vor der API-Definition das Rautezeichen #. um den automatischen Doxygen-Link zu erstellen.

   @par api_copy
   #otBorderAgentGetState
   

Hier ist ein vollständiges Beispiel für die Mindestanzahl von Doxygen-Kommentaren, die für automatisch einen OT-Kommandozeilenbefehl generieren:

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

Die HTML-Ausgabe finden Sie unter ba state auf. Erweiterte Beispiele und zusätzliche Optionen finden Sie in den folgenden Abschnitten.

Befehlszeilen-Vorlagenoptionen

CLI-Befehle sind nach einem kontinuierlichen Kommentarblock gruppiert, der mit dem ALIAS-Tag @cli. Es werden mehrere @code-Beispiele unterstützt.

Die Reihenfolge, in der Sie die einzelnen Tags angeben, ist wichtig.

• @cparam muss nach @code liegen
• Wenn Sie eine API-Beschreibung kopieren, muss @par api_copy nach @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

Weitere Informationen zur Verwendung der einzelnen ALIAS-Tags

Befehlsnamen

Beliebiger Text nach @cli wird als Header für den Befehlsnamen verwendet. Dieser Header wird verwendet in dynamische Verlinkung, zum Beispiel die Netdata-Veröffentlichungspräfix Befehl:

 * @cli netdata publish prefix

</ph>

Andere Befehle sind möglicherweise komplexer. Beispiel: netdata publish dnssrp unicast bietet mehrere Optionen:

1. Nach Adresse und Portnummer veröffentlichen
2. Nach Portnummer und der lokalen Mesh-Netzwerk-EID eines Geräts veröffentlichen

Wenn ein Befehl überlastet ist, verwenden Sie Klammern, um ihn eindeutig zu identifizieren.

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

Befehlsbeschreibungen

Es gibt drei Möglichkeiten, Befehlsbeschreibungen zu dokumentieren. Sie können den API-Beschreibung verwenden, verwenden Sie die API-Beschreibung, aber fügen Sie zusätzliche Informationen hinzu, oder eine eindeutige Beschreibung bereitstellen, die nur zum CLI-Befehl. In den nächsten Abschnitten werden die einzelnen Methoden erläutert.

Kopieren Sie die entsprechende API-Beschreibung.

Mit api_copy kopieren Sie die entsprechende API-Methode oder -Funktion. Wann? achten Sie darauf, dass die Beschreibung sowohl für die die API und den CLI-Befehl. Vermeiden Sie Formulierungen, die nur für ein , z. B. This function oder This method. Bevorzugen eine aktive Stimme haben, z. B. Gets the oder Sets the

 * @par api_copy
 * #otBorderAgentGetState

Fügen Sie der API-Beschreibung weitere Informationen hinzu

Wenn Sie api_copy verwenden möchten, aber zusätzliche Informationen hinzufügen möchten, gilt nur für den CLI-Befehl, verwenden Sie @par. Stellen Sie nach dem @par-Tag sicher, um zur nächsten Zeile zu gelangen.

 * @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.

Diese Absätze werden nach der API-Beschreibung angezeigt.

Nur Befehlszeilenspezifische Beschreibungen angeben

Einige CLI-Befehle verwenden mehrere APIs oder weichen vom API-Aufruf ab. Andere sind nicht mit einer API verknüpft, z. B. netdata help. Verwenden Sie @par, um eine separate Beschreibung anzugeben. Fügen Sie keinen Titel mit dem Titel @par hinzu und beginnen Sie Ihre Beschreibung am nächsten. Zeile. Verwenden Sie in diesem Szenario nicht @api_copy.

/**
 * @cli netdata help
 * @code
 * netdata help
 * ...
 * show
 * steeringdata
 * unpublish
 * Done
 * @endcode
 * @par
 * Gets a list of `netdata` CLI commands.
 */

Parameter

Definieren Sie Befehlsparameter mit @cparam und @ca.

• Setzen Sie optionale Argumente in eckige Klammern [ ].
• Verwenden Sie zwischen den Argumentauswahlen senkrechte Balken | (senkrechte Striche).
• Zum Anzeigen von Parameterdetails können Sie Sätze und Markdown-Listen eingeben unter dem @cparam-Tag.

Parameter mit Details

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

Informationen zur HTML-Ausgabe finden Sie unter Präfix der Veröffentlichung von netdata.

Parameter mit Markdown-Listen

Sie können Listen auch nach dem @cparam verwenden. Das ist hilfreich, wenn Sie liefern Details zu den verwendeten Befehlsargumenten.

 * @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.

Informationen zur HTML-Ausgabe finden Sie unter netdata show.

@cli-Blöcke müssen ein zusammenhängender Kommentar ohne Leerzeichen sein. Wenn Sie unter @cparam und dann einen weiteren Absatz darunter benötigen, verwenden Sie Punkt ., um die Liste manuell zu beenden.

* @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.

Weitere Beispiele finden Sie in der Listen:

APIs automatisch verknüpfen

Sie können eine Verknüpfung zu anderen API-Methoden oder -Funktionen mit #otFunctionName oder @sa. Geben Sie diese Links am Ende des Kommentarblocks der Befehlszeile ein.

/**
 * @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-Links werden in der Überschrift CLI- und API-Referenzen angezeigt. So überprüfen Sie den HTML-Code: Ausgabe, siehe Netdata-Veröffentlichungspräfix.

Automatische Verknüpfungen verhindern

Manchmal kann Doxygen ein normales Wort als Link zu einer Befehlszeilenklasse verwechseln, Beispiel: das Wort Joiner. Um zu verhindern, dass Doxygen auf Suchbegriffe oder Kurse verweist Namen verwenden, setzen Sie den Operator % vor dem Wort, Beispiel:

Clear the %Joiner discerner

Weitere Informationen finden Sie unter Automatische Linkgenerierung im Doxygen-Leitfaden.

Automatisch mit anderen Befehlen verknüpfen

Mit @csa können Sie eine Verknüpfung zu anderen Befehlen herstellen.

* @csa{netdata publish dnssrp anycast}

Wenn ein Befehl überlastet ist, schließen Sie die Klammern ein und fügen Sie ein Komma falls zutreffend. Verwenden Sie keine Leerzeichen innerhalb der Klammern:

* @csa{netdata publish dnssrp unicast (addr,port)}
* @csa{netdata publish dnssrp unicast (mle)}

Doxygen-Spezialbefehle

Befehle in der Befehlszeile unterstützen die folgenden Doxygen-ALIASSE und speziellen Befehle:

Vom Skript make pretty unterbrochene Zeilen reparieren

Einige Codekommentare wie Befehlszeilenparameter oder die Befehlsausgabe müssen aktiviert sein damit sie korrekt in der openthread.io-Referenz gerendert werden. make pretty legt jedoch eine Spaltenbreite fest, was das gerenderte für lange Zeilen ausgeben.

Dieses Problem kann behoben werden, indem Sie Zeilenumbrüche einfügen und diese einschließen mit einem HTML-Kommentar-Tag verwenden, wie in zwei Beispielen unten gezeigt.

Das erste Beispiel ist der Befehl dns resolve, der bis zu sechs Parameter. Um die Syntax mit Doxygen korrekt zu rendern, während sie weiterhin übergeben wird Die make pretty-Prüfung müssen die Parameter auf drei Zeilen aufgeteilt sein. in der Quelle:

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

Das zweite Beispiel ist die Ausgabe des Befehls history ipaddr list 5. Damit die Ausgabe korrekt gerendert wird und die make pretty-Prüfung dennoch besteht, Jede der fünf Ausgabezeilen muss wie folgt in zwei Zeilen aufgeteilt werden:

* 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