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.
Suchen Sie im Verzeichnis
openthread/src/cli
nach dem zugehörigenCmd
. Wenn Sie beispielsweiseba state
finden möchten, suchen Sie nachCmd("ba")
. Jedem Befehl ist eine Funktionsvorlage zugeordnet:template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])
Suchen Sie in der Funktionsvorlage nach der richtigen Befehlslogik. Zum Beispiel
ba state
:else if (aArgs[0] == "state")
Starten Sie den Doxygen-Block
@cli
, bevor die Logik beginnt:/** * @cli ba state
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 StandardantwortDone
.* @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:
Suchen Sie im Verzeichnis
openthread/include/openthread
nach der zugehörigen API. Beispiel:ba state
wirdotBorderAgentGetState
zugeordnet.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:
- Nach Adresse und Portnummer veröffentlichen
- 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.
APIs automatisch verknüpfen
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.
Automatische Links verhindern
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.
Automatisch mit anderen Befehlen verknüpfen
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