Polecenia interfejsu wiersza poleceń generujemy na podstawie plików źródłowych interfejsu wiersza poleceń w repozytorium openthread w GitHubie.
Ten przewodnik zawiera instrukcje korzystania z niestandardowych komentarzy Doxygen, których używamy do tworzenia listy poleceń.
Rozpocznij
Aby udokumentować polecenie interfejsu wiersza poleceń, wykonaj te czynności. Ważne jest, by wykonać te czynności w podanej kolejności.
W katalogu
openthread/src/cli
znajdź powiązany plikCmd
. Na przykład, aby znaleźćba state
, wyszukajCmd("ba")
. Każde polecenie będzie miało powiązany szablon funkcji:template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])
W szablonie funkcji znajdź prawidłową logikę polecenia. Na przykład
ba state
:else if (aArgs[0] == "state")
Zanim zacznie działać logika, uruchom blok Doxygen
@cli
:/** * @cli ba state
Następnie tuż pod polem
@cli
dodaj przykłady przy użyciu elementu@code
. Podaj co najmniej jeden przykład. Nie uwzględniaj promptu>
i udokumentuj pełne dane wyjściowe, w tym standardową odpowiedźDone
.* @code * ba state * Started * Done * @endcode
Polecenia interfejsu wiersza poleceń zapewniają dostęp z poziomu wiersza poleceń do typowych metod i funkcji interfejsu API, dlatego niektóre z nich mają taki sam opis jak odpowiadające im interfejsy API. Jeśli opis polecenia jest taki sam, wykonaj te czynności:
Znajdź powiązany interfejs API w katalogu
openthread/include/openthread
. Na przykład zapisba state
jest mapowany na adresotBorderAgentGetState
.Użyj polecenia
api_copy
, a potem wpisz nazwę interfejsu API bezpośrednio pod nim. Pamiętaj, aby przed definicją interfejsu API użyć znaku funta#
, aby utworzyć automatyczne połączenie Doxygen.@par api_copy #otBorderAgentGetState
Oto pełny przykład minimalnej liczby komentarzy Doxygen wymaganych do automatycznego wygenerowania polecenia interfejsu wiersza poleceń OT:
/**
* @cli ba state
* @code
* ba state
* Started
* Done
* @endcode
* @par api_copy
* #otBorderAgentGetState
*/
Aby sprawdzić dane wyjściowe HTML, sprawdź stan ba. Przykłady zaawansowane i dodatkowe opcje znajdziesz w poniższych sekcjach.
Opcje szablonu interfejsu wiersza poleceń
Polecenia interfejsu wiersza poleceń są pogrupowane według jednego ciągłego bloku komentarzy, zaczynając od tagu ALIAS @cli
. Obsługiwanych jest wiele przykładów z elementu @code
.
Kolejność określania poszczególnych tagów jest ważna.
@cparam
musi przypadać po@code
- Jeśli kopiujesz opis interfejsu API,
@par api_copy
musi znajdować się po@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
Teraz dowiedz się więcej o korzystaniu z poszczególnych tagów ALIAS.
Nazwy poleceń
Każdy tekst występujący po @cli
staje się nagłówkiem nazwy polecenia. Ten nagłówek jest używany w linkach dynamicznych, na przykład w poleceniu netdata publikacji:
* @cli netdata publish prefix
Inne polecenia mogą być bardziej złożone. Na przykład netdata publish dnssrp unicast
udostępnia kilka opcji:
- Opublikuj według adresu i numeru portu
- Publikuj według numeru portu i lokalnego identyfikatora EID urządzenia w sieci typu mesh
Jeśli polecenie jest przeciążone, użyj nawiasów, aby je jednoznacznie zidentyfikować.
* @cli netdata publish dnssrp unicast (mle)
* @cli netdata publish dnssrp unicast (addr,port)
Opisy poleceń
Opisy poleceń możesz dokumentować na 3 sposoby. Możesz skopiować opis interfejsu API, użyć jego opisu, ale dodać dodatkowe informacje, lub podać całkowicie unikalny opis, który należy tylko do polecenia interfejsu wiersza poleceń. W kolejnych sekcjach omówimy każdą z tych metod.
Skopiuj odpowiedni opis interfejsu API
Użyj api_copy
, aby skopiować odpowiednią metodę lub funkcję interfejsu API. Podczas kopiowania interfejsów API upewnij się, że opis działa zarówno w przypadku interfejsu API, jak i polecenia interfejsu wiersza poleceń. Unikaj wyrażeń, które odnoszą się tylko do funkcji, np. This function
lub This method
. Wolę głos czynny, np. Gets the
lub Sets the
.
* @par api_copy
* #otBorderAgentGetState
Dodaj więcej informacji do opisu interfejsu API
Jeśli chcesz używać api_copy
, ale chcesz dodać dodatkowe informacje, które mają zastosowanie tylko do polecenia interfejsu wiersza poleceń, użyj @par
. Pamiętaj, aby przejść do następnego wiersza po tagu @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.
Akapity wyświetlają się po opisie interfejsu API.
Podaj tylko opisy specyficzne dla interfejsu wiersza poleceń
Niektóre polecenia interfejsu wiersza poleceń korzystają z wielu interfejsów API lub różnią się od wywołania interfejsu API.
Inne nie mają powiązanego interfejsu API, np. netdata help
.
Aby podać osobny opis, użyj operatora @par
.
Nie dodawaj tytułu @par
i zacznij opis od następnego wiersza. W tym przypadku nie używaj @api_copy
.
/**
* @cli netdata help
* @code
* netdata help
* ...
* show
* steeringdata
* unpublish
* Done
* @endcode
* @par
* Gets a list of `netdata` CLI commands.
*/
Parametry
Zdefiniuj parametry polecenia za pomocą właściwości @cparam
i @ca
.
- Umieść opcjonalne argumenty w nawiasach kwadratowych
[ ]
. - Między różnymi argumentami użyj pionowych słupków
|
(pionowych kresek). - Aby wyświetlić szczegóły parametrów, możesz wpisywać zdania i listy Markdown pod tagiem
@cparam
.
Parametry ze szczegółami
* @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}.
Aby sprawdzić dane wyjściowe HTML, zapoznaj się z prefiksem publikowania danych netdata.
Parametry z listami w formacie Markdown
Możesz też używać list po @cparam
. Jest to przydatne, gdy chcesz podać szczegółowe informacje o używanych argumentach polecenia.
* @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.
Aby sprawdzić dane wyjściowe HTML, przeczytaj artykuł netdata show.
Bloki @cli
muszą być jednym ciągłym komentarzem bez spacji. Jeśli dodajesz listę poniżej @cparam
, a pod nią potrzebujesz kolejnego akapitu, użyj kropki .
, aby ręcznie zamknąć listę.
* @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.
Więcej przykładów znajdziesz na listach w Doxygen.
Automatycznie łącz interfejsy API
Połączenie z innymi metodami lub funkcjami interfejsu API możesz tworzyć za pomocą #otFunctionName
lub @sa
. Wpisz te linki na końcu bloku komentarzy interfejsu wiersza poleceń.
/**
* @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
*/
Linki @sa
są wyświetlane w nagłówku CLI and API References (Materiały dotyczące interfejsu wiersza poleceń i interfejsów API). Aby sprawdzić dane wyjściowe HTML, zapoznaj się z prefiksem publikowania danych netdata.
Zapobieganie automatycznym linkom
Czasami Doxygen może pomylić zwykłe słowo z linkiem do klasy interfejsu wiersza poleceń, na przykład słowo Joiner
. Aby uniemożliwić stosowanie linków Doxygen do słów kluczowych lub nazw klas używanych w zdaniu, użyj przed nim operatora %
, na przykład:
Clear the %Joiner discerner
Więcej informacji znajdziesz w sekcji dotyczącej automatycznego generowania linków w przewodniku Doxygen.
Automatyczne łączenie z innymi poleceniami
Aby połączyć z innymi poleceniami, użyj polecenia @csa
.
* @csa{netdata publish dnssrp anycast}
Jeśli polecenie jest przeciążone, podaj nawiasy i w razie potrzeby dodaj przecinek. Nie stosuj spacji w nawiasach:
* @csa{netdata publish dnssrp unicast (addr,port)}
* @csa{netdata publish dnssrp unicast (mle)}
Specjalne polecenia Doxygen
Polecenia interfejsu wiersza poleceń obsługują następujące ALIASY doxygen i polecenia specjalne:
ALIAS | Przykład | Opis |
---|---|---|
@klip | Port @cli ba | Nazwa polecenia. Uruchamia blok komentarzy interfejsu wiersza poleceń. |
@kod | @code ba port 41953 Gotowe @endcode |
Przykład polecenia. |
@ca | [@ca{prefix}] | Argument polecenia. Użyj nawiasów [ ] jako argumentów opcjonalnych. |
@cparam | @cparam joiner discerner @ca{discerner} Szczegóły parametru. |
Parametry polecenia. |
@par | @par Opcjonalny opis interfejsu wiersza poleceń. |
Akapity związane z interfejsem wiersza poleceń. |
@csa | @csa{prefix add} | Zobacz też Command. Jest powiązany z innym poleceniem. |
@sa | @sa otBorderRouterConfig | Zobacz też. Tworzy link do dokumentacji API. |
@Ogółem | @Ogółem | Tworzy link do przeglądu interfejsu wiersza poleceń OpenThread. |
@netdata | @netdata | Tworzy link do wyświetlania danych sieci i zarządzania nimi za pomocą interfejsu wiersza poleceń OT. |
@zbiór danych | @zbiór danych | Tworzy link do wyświetlania zbiorów danych i zarządzania nimi za pomocą interfejsu wiersza poleceń OT. |
@udp | @udp | Tworzy link do testowania funkcjonalności UDP za pomocą interfejsu wiersza poleceń OT. |
@moreinfo | @moreinfo{@netdata} | Tworzy link rekomendacyjny. |
@notatka | @note Ważne objaśnienie. | Tworzy pole objaśnienia notatki. |
Naprawianie wierszy przerywanych przez skrypt make pretty
Niektóre komentarze do kodu, takie jak parametry interfejsu wiersza poleceń lub dane wyjściowe poleceń, muszą znajdować się w jednym wierszu, aby były prawidłowo renderowane w dokumentacji openthread.io.
make pretty
nakłada jednak limit szerokości kolumny, co może zakłócać renderowanie danych wyjściowych w przypadku długich wierszy.
Taką sytuację można rozwiązać, dodając podziały wierszy i umieszczając je w tagu komentarza HTML, jak w 2 przykładach poniżej.
Pierwszym przykładem jest polecenie dns resolve
, które może przyjmować do 6 parametrów. Aby poprawnie renderować składnię za pomocą Doxygen, a jednocześnie uzyskać kontrolę make pretty
, parametry w źródle muszą zostać podzielone na 3 wiersze:
* @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}]
Drugi przykład to dane wyjściowe polecenia history ipaddr list 5
.
Aby dane wyjściowe renderowały się prawidłowo i miały kontrolę make pretty
, każdy z 5 wierszy danych wyjściowych musi zostać podzielony na 2 wiersze w ten sposób:
* 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