OT-CLI-Befehle aktualisieren

Quelle auf GitHub ansehen

Wir generieren Befehlszeilenbefehle aus den Befehlszeilen-Quelldateien im GitHub-Repository openthread.

Dieser Leitfaden enthält Anweisungen zur Verwendung unserer benutzerdefinierten Doxygen-Kommentare, die wir zum Erstellen der Befehlsliste verwenden.

Mehr erfahren

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

  1. Suchen Sie im Verzeichnis openthread/src/cli nach dem zugehörigen Cmd. Wenn Sie beispielsweise ba state finden möchten, suchen Sie nach Cmd("ba"). 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. Starten Sie den Doxygen-Block @cli, bevor die Logik beginnt:

    /**
 * @cli ba state

  4. Fügen Sie als Nächstes direkt unter @cli Beispiele mit @code hinzu. Nehmen Sie mindestens ein Beispiel auf. Fügen Sie nicht die >-Eingabeaufforderung ein und dokumentieren Sie die vollständige Rückgabeausgabe, einschließlich der Standardantwort Done.

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

Da CLI-Befehle Befehlszeilenzugriff auf gängige API-Methoden und -Funktionen ermöglichen, haben einige Befehle dieselbe Beschreibung wie die entsprechende API. Wenn die Befehlsbeschreibung identisch ist, führen Sie die folgenden Schritte aus:

  1. Suchen Sie im Verzeichnis openthread/include/openthread nach der zugehörigen API. Beispiel: ba state wird otBorderAgentGetState zugeordnet.

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

    @par api_copy
#otBorderAgentGetState

Hier ist ein vollständiges Beispiel für Doxygen-Kommentare, die mindestens erforderlich sind, um einen OT-Befehlszeilenbefehl automatisch zu generieren:

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

Informationen zur Überprüfung der HTML-Ausgabe finden Sie unter ba state. Erweiterte Beispiele und zusätzliche Optionen finden Sie in den folgenden Abschnitten.

Optionen für Befehlszeilenvorlage

CLI-Befehle sind in einem zusammenhängenden Kommentarblock gruppiert, der mit dem ALIAS-Tag @cli beginnt. 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 stehen.
 * @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

Erfahren Sie als Nächstes mehr über die Verwendung der einzelnen ALIAS-Tags.

Befehlsnamen

Jeder Text nach @cli wird zum Befehlsnamenheader. Dieser Header wird bei der dynamischen Verknüpfung verwendet, z. B. mit dem Befehl netdatapublish Präfix:

 * @cli netdata publish prefix

Andere Befehle sind möglicherweise komplexer. netdata publish dnssrp unicast bietet beispielsweise einige Optionen:

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

Wenn ein Befehl überlastet ist, verwenden Sie Klammern, um den Befehl 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 die API-Beschreibung kopieren, die API-Beschreibung verwenden, aber zusätzliche Informationen hinzufügen oder eine absolut eindeutige Beschreibung angeben, die nur zum CLI-Befehl gehört. In den nächsten Abschnitten werden jede dieser Methoden näher erläutert.

Kopieren Sie die entsprechende API-Beschreibung.

Verwenden Sie api_copy, um die entsprechende API-Methode oder -Funktion zu kopieren. Achten Sie beim Kopieren von APIs darauf, dass die Beschreibung sowohl für die API als auch für den CLI-Befehl funktioniert. Vermeiden Sie Formulierungen, die nur für eine Funktion gelten, z. B. This function oder This method. Wählen Sie eine aktive Stimme aus, z. B. Gets the oder Sets the.

 * @par api_copy
 * #otBorderAgentGetState

Weitere Informationen zur API-Beschreibung hinzufügen

Wenn Sie api_copy verwenden möchten, aber zusätzliche Informationen hinzufügen möchten, die nur für den Befehl der Befehlszeile gelten, verwenden Sie @par. Achten Sie darauf, nach dem @par-Tag die nächste Zeile zu öffnen.

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

Geben Sie nur Befehlszeilenspezifische Beschreibungen an

Einige CLI-Befehle verwenden mehrere APIs oder unterscheiden sich vom API-Aufruf. Andere Nutzer haben keine verknüpfte API, z. B. netdata help. Wenn Sie eine separate Beschreibung angeben möchten, verwenden Sie @par. Geben Sie keinen @par-Titel an und beginnen Sie mit der Beschreibung in der 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 Klammern [ ].
  • Verwenden Sie senkrechte Striche | (senkrechte Striche) zwischen den Argumentoptionen.
  • Wenn Sie Details zu den Parametern einblenden möchten, können Sie unter dem Tag @cparam Sätze und Markdown-Listen eingeben.

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 Netdata-Veröffentlichung.

Parameter mit Markdown-Listen

Du kannst auch Listen nach dem @cparam verwenden. Dies ist hilfreich, wenn Sie Details zu den verwendeten Befehlsargumenten angeben möchten.

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

Bei @cli-Blöcken muss es sich um einen zusammenhängenden Kommentar ohne Leerzeichen handeln. Wenn Sie eine Liste unter @cparam hinzufügen und dann einen weiteren Absatz darunter benötigen, können Sie die Liste mit einem .-Punkt manuell 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 den Lists von Doxygen.

Mit #otFunctionName oder @sa können Sie eine Verknüpfung zu anderen API-Methoden oder -Funktionen herstellen. Geben Sie diese Links am Ende des Kommandoblocks 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 unter der Überschrift Befehlszeile und API-Referenzen angezeigt. Informationen zur Überprüfung der HTML-Ausgabe finden Sie unter Präfix der Netdata-Veröffentlichung.

Manchmal verwechselt Doxygen ein normales Wort als Link zu einer Befehlszeilenklasse, z. B. das Wort Joiner. Wenn Sie verhindern möchten, dass Doxygen mit Schlüsselwörtern oder Klassennamen in einem Satz verknüpft wird, verwenden Sie den Operator % vor dem Wort. Beispiel:

Clear the %Joiner discerner

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

Verwenden Sie @csa, um eine Verknüpfung zu anderen Befehlen herzustellen.

* @csa{netdata publish dnssrp anycast}

Wenn ein Befehl überlastet ist, fügen Sie die Klammern hinzu und fügen Sie gegebenenfalls ein Komma hinzu. Verwenden Sie innerhalb der Klammern keine Leerzeichen:

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

Doxygen-Sonderbefehle

CLI-Befehle unterstützen die folgenden Doxygen-ALIASES und speziellen Befehle:

ALIAS Beispiel Beschreibung
@cli @cli ba port Befehlsname. Startet einen Befehlszeilen-Kommentarblock.
@Code @code
ba port
41953
Fertig
@endcode		 Beispiel für den Befehl
@ca [@ca{Präfix}] Befehlsargument. Optionale Argumente: [ ]
@cparam @cparam Joiner discerner @ca{discerner}
Parameterdetails.		 Befehlsparameter.
@par @par
Optionale Befehlszeilenbeschreibung		 CLI-spezifische Absätze
@csa @csa{prefix add} Befehl (siehe auch). Verlinkt zu einem anderen Befehl.
@sa @sa: otBorderRouterConfig Siehe auch. Erstellt einen Link zu einer API-Referenz.
@Übersicht @Übersicht Erstellt einen Link zur Übersicht über die OpenThread-Befehlszeile.
@netdata @netdata Erstellt einen Link zu Display and Manage Network Data with OT CLI.
@Dataset @Dataset Erstellt einen Link zu Display and Manage Datasets with OT CLI (Datasets mit OT CLI anzeigen und verwalten).
@udp @udp Erstellt einen Link zum Testen der UDP-Funktionalität mit der OT CLI.
@mehrinfo @moreinfo{@netdata} Erstellt einen Empfehlungslink.
@Notiz @note Wichtige Zusatzinformationen. Erstellt ein Feld mit Zusatzinformationen für Notizen.

Korrektur von Zeilen, die vom Skript make pretty unterbrochen wurden

Einige Codekommentare, z. B. CLI-Parameter oder Befehlsausgaben, müssen sich in einer einzigen Zeile befinden, damit sie in der Referenz zu openthread.io korrekt gerendert werden. Bei make pretty gilt jedoch eine Begrenzung der Spaltenbreite, wodurch die gerenderte Ausgabe bei langen Zeilen unterbrochen werden kann.

Sie können diese Situation umgehen, indem Sie Zeilenumbrüche hinzufügen und diese in ein HTML-Kommentar-Tag einfügen, wie in zwei Beispielen unten gezeigt.

Das erste Beispiel ist der Befehl dns resolve, der bis zu sechs Parameter enthalten kann. Damit die Syntax mit Doxygen korrekt gerendert wird, während die make pretty-Prüfung weiterhin besteht, müssen die Parameter auf drei Zeilen in der Quelle aufgeteilt werden:

* @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 trotzdem die Prüfung make pretty besteht, muss jede der fünf Ausgabezeilen so 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