Ta strona została przetłumaczona przez Cloud Translation API.

Aktualizowanie poleceń interfejsu wiersza poleceń OT

Generujemy polecenia interfejsu wiersza poleceń. z plików źródłowych interfejsu wiersza poleceń w openthread repozytorium GitHub.

Ten przewodnik zawiera instrukcje na temat korzystania z naszych niestandardowych komentarzy Doxygen którego używamy do utworzenia listy poleceń.

Rozpocznij

Aby udokumentować polecenie interfejsu wiersza poleceń, wykonaj poniższe czynności. Ważne jest, aby wykonaj te czynności w podanej kolejności.

Znajdź powiązane Cmd z: openthread/src/cli katalogu. Aby na przykład znaleźć „ba state”, wyszukaj Cmd("ba"). Każde polecenie będzie mieć powiązany szablon funkcji:
```
template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])
```
W szablonie funkcji znajdź właściwą logikę polecenia. Przykład: ba state:
```
else if (aArgs[0] == "state")
```
Zanim zacznie działać logika, uruchom blok Doxygenu w aplikacji @cli:
```
/**
 * @cli ba state
```
Następnie tuż pod adresem @cli dodaj przykłady za pomocą właściwości @code. Uwzględnij w co najmniej jeden przykład. Nie dodawaj prompta > i upewnij się, że udokumentuj pełne dane wyjściowe, w tym standardową odpowiedź Done.
```
 * @code
 * ba state
 * Started
 * Done
 * @endcode
```

Ponieważ polecenia interfejsu wiersza poleceń zapewniają dostęp z poziomu wiersza poleceń do popularnych metod interfejsu API i funkcje, niektóre z nich mają taki sam opis odpowiadający mu interfejs API. Jeśli opis polecenia jest taki sam, uzupełnij następujące kroki:

Znajdź powiązany interfejs API w openthread/include/openthread katalogu. Na przykład ba state wskazuje miejsce otBorderAgentGetState.
Użyj polecenia api_copy, a następnie wpisz nazwę interfejsu API bezpośrednio pod nim. Pamiętaj, aby przed definicją interfejsu API umieścić znak #. aby utworzyć automatyczne połączenie z Doxygen.
```
@par api_copy
#otBorderAgentGetState
```

Oto pełny przykład minimalnej liczby komentarzy doxygenowych wymaganych do automatycznie wygeneruj polecenie interfejsu wiersza poleceń OT:

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

Aby sprawdzić dane wyjściowe HTML, zapoznaj się z artykułem stan ba [stan]. Zaawansowane przykłady i dodatkowe opcje znajdziesz w kolejnych sekcjach.

Opcje szablonu interfejsu wiersza poleceń

Polecenia interfejsu wiersza poleceń są pogrupowane według jednego bloku komentarza, począwszy od Tag ALIAS @cli. Obsługiwanych jest kilka przykładów tego formatu: @code.

Kolejność wyświetlania tagów jest ważna.

Wartość @cparam musi być późniejsza niż @code
Jeśli kopiujesz opis interfejsu API, @par api_copy musi następować 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

Następnie dowiedz się więcej o sposobie użycia tagów ALIAS.

Nazwy poleceń

Każdy tekst po fragmencie @cli staje się nagłówkiem nazwy polecenia. Ten nagłówek jest używany w dynamiczne linki, na przykład prefiks publikowania netdata polecenie:

 * @cli netdata publish prefix

.
Ważne: w nazwach poleceń nie używaj argumentów ani znaków specjalnych.

Inne polecenia mogą być bardziej złożone. 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 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żna dokumentować na 3 sposoby. Możesz skopiować API opis, należy użyć opisu interfejsu API, ale podać dodatkowe informacje, lub podaj całkowicie niepowtarzalny opis, który należy tylko do Polecenie interfejsu wiersza poleceń. W kolejnych sekcjach omówimy każdą z tych metod.

Skopiuj odpowiedni opis interfejsu API

Użyj narzędzia api_copy, aby skopiować odpowiednią metodę lub funkcję interfejsu API. Kiedy skopiujesz interfejsy API, upewnij się, że opis będzie działać API i polecenie interfejsu wiersza poleceń. Unikaj wyrażeń, które odnoszą się tylko do funkcji, na przykład This function lub This method. Preferowane użyć głosu czynnego, na przykład Gets the lub Sets the.

 * @par api_copy
 * #otBorderAgentGetState

Dodaj więcej informacji do opisu interfejsu API

Jeśli chcesz korzystać z usługi api_copy, ale musisz podać dodatkowe informacje, które dotyczy tylko polecenia interfejsu wiersza poleceń, użyj @par. Po tagu @par upewnij się, aby przejść do następnego wiersza.

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

Te akapity wyświetlają się po opisie interfejsu API.

Podaj tylko opisy dotyczące interfejsu wiersza poleceń

Niektóre polecenia interfejsu wiersza poleceń używają wielu interfejsów API lub różnią się od wywołań interfejsu API. Inne nie mają powiązanego interfejsu API, np. netdata help. Aby podać osobny opis, użyj @par. Nie podawaj tytułu w języku: @par, a opis zacznij od następnego . W takim 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ą @cparam i @ca.

Umieść argumenty w nawiasach kwadratowych [ ].
Używaj pionowych słupków | (kresek pionowych) między możliwymi argumentami.
Aby wyświetlić szczegóły parametru, 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, przeczytaj prefiks publikowania danych netto.

Parametry z listami Markdown

Możesz też użyć list po @cparam. To przydatne, gdy chcesz podaj 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, zobacz netdata show.

Bloki (@cli) muszą być jednym ciągłym komentarzem bez spacji. Jeśli dodasz do listy poniżej @cparam, a następnie brakuje kolejnego akapitu pod tą listą, użyj okres ., aby ręcznie zakończyć 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 tutaj: Listy.

Automatycznie łącz interfejsy API

Z innymi metodami lub funkcjami interfejsu API możesz łączyć się za pomocą właściwości #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 Dokumentacja interfejsu wiersza poleceń i interfejsu API. Aby sprawdzić kod HTML dane wyjściowe znajdziesz w artykule prefiks publikowania netdata.

Zapobieganie automatycznym linkom

Czasami Doxygen może pomylić zwykłe słowo jako link do klasy interfejsu wiersza poleceń, na przykład na przykład słowo Joiner. Aby uniemożliwić łączenie usługi Doxygen ze słowami kluczowymi lub zajęciami imiona i nazwiska używane w zdaniu, użyj operatora % przed słowem, np.:

Clear the %Joiner discerner

Więcej informacji: Automatyczne generowanie linków w przewodniku Doxygen.

Automatycznie łącz z innymi poleceniami

Użyj @csa, aby połączyć z innymi poleceniami.

* @csa{netdata publish dnssrp anycast}

Jeśli polecenie jest przeciążone, uwzględnij nawiasy i dodaj przecinek w odpowiednich przypadkach. Nie stosuj spacji w nawiasach:

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

Specjalne polecenia dotyczące Doxygen

Polecenia interfejsu wiersza poleceń obsługują następujące polecenia ALIASES Doxygen i polecenia specjalne:

ALIAS	Przykład	Opis
@cli	Port @cli ba	Nazwa polecenia. Uruchamia blok komentarza interfejsu wiersza poleceń.
@kod	@code ba port 41953 Done @endcode	Przykład polecenia.
@ca	[@ca{prefix}]	Argument polecenia. Opcjonalne argumenty możesz dodać w nawiasach kwadratowych `[ ]`.
@cparam	@cparam Joiner discerner @ca{discerner} Szczegóły parametru.	Parametry polecenia.
@par	@par Opcjonalny opis interfejsu wiersza poleceń.	akapity dotyczące interfejsu wiersza poleceń.
@csa	@csa{prefix add}	Polecenie: Zobacz też. Link do innego polecenia.
@sa	Konfiguracja @sa otBorderRouterConfig	Zobacz też. Tworzy link do dokumentacji interfejsu API.
@omówienie	@omówienie	Tworzy link do omówienia interfejsu wiersza poleceń OpenThread.
@netdata	@netdata	Tworzy link do wyświetlania danych sieci i zarządzania nimi za pomocą OT CLI.
@dataset	@dataset	Tworzy link do wyświetlania zbiorów danych i zarządzania nimi za pomocą interfejsu wiersza poleceń OT.
@udp	@udp	Tworzy link do testowania funkcji 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 uszkodzonych przez skrypt `make pretty`

Niektóre komentarze do kodu, takie jak parametry interfejsu wiersza poleceń lub dane wyjściowe poleceń, muszą być włączone jeden wiersz, aby były prawidłowo renderowane w odwołaniu openthread.io. make pretty narzuca jednak limit szerokości kolumny, co może spowodować uszkodzenie renderowania dla długich wierszy.

Można to zrobić, dodając podziały wierszy i dołączając je z tagiem komentarza HTML, jak pokazano w dwóch poniższych przykładach.

Pierwszy przykład to polecenie dns resolve, które może zająć maksymalnie 6 . Aby prawidłowo wyrenderować składnię za pomocą Doxygen, nadal przesyłając podczas sprawdzania make pretty parametry muszą zostać rozdzielone na 3 wiersze w źródle:

* @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 były renderowane prawidłowo i nadal przeszły kontrolę make pretty: każdy z 5 wierszy wyjściowych musi zostać podzielony na 2 wiersze w następujący 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