Aktualizowanie poleceń interfejsu wiersza poleceń OT

Wyświetl źródło na GitHubie

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.

  1. W katalogu openthread/src/cli znajdź powiązany plik Cmd. Na przykład, aby znaleźć ba state, wyszukaj Cmd("ba"). Każde polecenie będzie miało powiązany szablon funkcji:

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

  2. W szablonie funkcji znajdź prawidłową logikę polecenia. Na przykład ba state:

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

  3. Zanim zacznie działać logika, uruchom blok Doxygen @cli:

    /**
 * @cli ba state

  4. 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:

  1. Znajdź powiązany interfejs API w katalogu openthread/include/openthread. Na przykład zapis ba state jest mapowany na adres otBorderAgentGetState.

  2. 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:

  1. Opublikuj według adresu i numeru portu
  2. 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.

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.

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.

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