OT CLI Komutlarını Güncelleme

Kaynağı GitHub'da görüntüleyin

CLI Komutlarını, openthread GitHub deposundaki CLI kaynak dosyalarından oluştururuz.

Bu kılavuzda, komut listesini oluşturmak için kullandığımız özel Doxygen yorumlarımızın nasıl kullanılacağıyla ilgili talimatlar sağlanmaktadır.

Başlayın

Bir CLI komutunu belgelemek için aşağıdaki adımları tamamlayın. Bu adımları sırasıyla uygulamanız önemlidir.

  1. openthread/src/cli dizininden ilgili Cmd öğesini bulun. Örneğin, ba state için Cmd("ba") araması yapın. Her komutun ilişkili bir işlev şablonu olur:

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

  2. İşlev şablonunda doğru komut mantığını bulun. Örneğin, ba state:

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

  3. Mantık başlamadan önce @cli Doxygen blokunu başlatın:

    /**
 * @cli ba state

  4. Daha sonra, @cli öğesinin hemen altına @code kullanarak örnekler ekleyin. En az bir örnek ekleyin. > istemini eklemeyin ve standart Done yanıtı da dahil olmak üzere tam dönüş çıkışını belgelediğinizden emin olun.

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

CLI komutları, yaygın API yöntemlerine ve işlevlerine komut satırı erişimi sağladığından bazı komutlar, karşılık gelen API'leriyle aynı açıklamayı paylaşır. Komut açıklaması aynıysa aşağıdaki adımları tamamlayın:

  1. openthread/include/openthread dizininden ilişkilendirilmiş API'yi bulun. Örneğin, ba state, otBorderAgentGetState ile eşlenir.

  2. api_copy komutunu kullanıp API adını hemen altına girin. Otomatik Doxygen bağlantısını oluşturmak için API tanımının önünde sterlin işaretini # kullandığınızdan emin olun.

    @par api_copy
#otBorderAgentGetState

Otomatik olarak bir OT KSA komutu oluşturmak için gereken minimum Doxygen yorumuyla ilgili tam bir örneği aşağıda bulabilirsiniz:

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

HTML çıkışını incelemek için ba durumuna bakın. Gelişmiş örnekler ve ek seçenekler için aşağıdaki bölümlere bakın.

KSA şablonu seçenekleri

CLI komutları, ALIAS etiketi @cli ile başlayan tek bir sürekli yorum bloğuna göre gruplandırılır. Birden fazla @code örneği desteklenmektedir.

Her bir etiketi belirttiğiniz sıra önemlidir.

  • @cparam, @code tarihinden sonra gelmelidir
  • Bir API açıklamasını kopyalıyorsanız @par api_copy, @cparam tarihinden sonra gelmelidir
 * @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

Şimdi, her bir ALIAS etiketinin nasıl kullanıldığı hakkında daha fazla bilgi edinin.

Komut adları

@cli ifadesinden sonraki tüm metinler komut adı üstbilgisi olur. Bu başlık, dinamik bağlantıda (örneğin netdata yayınlama ön eki komutu) kullanılır:

 * @cli netdata publish prefix

Diğer komutlar daha karmaşık olabilir. Örneğin, netdata publish dnssrp unicast birkaç seçenek sunar:

  1. Adres ve bağlantı noktası numarası ile yayınlama
  2. Bağlantı noktası numarası ve cihazın Mesh-Local EID kimliğine göre yayınla

Bir komut aşırı yüklenirse komutu benzersiz bir şekilde tanımlamak için parantez kullanın.

 * @cli netdata publish dnssrp unicast (mle)
 * @cli netdata publish dnssrp unicast (addr,port)

Komut açıklamaları

Komut açıklamalarını belgelemenin üç yolu vardır. API açıklamasını kopyalayabilir, API açıklamasını kullanabilir ancak ek bilgiler ekleyebilir veya yalnızca CLI komutuna ait tamamen benzersiz bir açıklama girebilirsiniz. Sonraki bölümlerde, her bir yöntemi ele alacağız.

İlgili API açıklamasını kopyala

İlgili API yöntemini veya işlevini kopyalamak için api_copy kullanın. API'leri kopyaladığınızda açıklamanın hem API hem de CLI komutu için çalışacağından emin olun. This function veya This method gibi yalnızca bir işlev için geçerli olan ifadeler kullanmaktan kaçının. Gets the veya Sets the gibi etkin bir sesi tercih edin.

 * @par api_copy
 * #otBorderAgentGetState

API açıklamasına daha fazla bilgi ekleyin

api_copy kullanmak istiyor ancak yalnızca CLI komutu için geçerli olan ek bilgiler eklemeniz gerekiyorsa @par değerini kullanın. @par etiketinden sonra, bir sonraki satıra geçtiğinizden emin olun.

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

Bu paragraflar, API açıklamasından sonra gösterilir.

Yalnızca KSA'ya özel açıklamalar sağlayın

Bazı CLI komutları birden fazla API kullanır veya API çağrısından farklıdır. Diğerlerinin ilişkilendirilmiş bir API'si yoktur (örneğin, netdata help). Ayrı bir açıklama girmek için @par kullanın. @par başlık eklemeyin ve açıklamanıza bir sonraki satırdan başlayın. Bu senaryoda @api_copy kullanmayın.

/**
 * @cli netdata help
 * @code
 * netdata help
 * ...
 * show
 * steeringdata
 * unpublish
 * Done
 * @endcode
 * @par
 * Gets a list of `netdata` CLI commands.
 */

Parametreler

@cparam ve @ca kullanarak komut parametrelerini tanımlayın.

  • İsteğe bağlı bağımsız değişkenlerin başına ve sonuna köşeli parantez [ ] koyun.
  • Bağımsız değişken seçenekleri arasında dikey çubuklar | (dikey çizgi) kullanın.
  • Parametre ayrıntılarını görüntülemek için @cparam etiketinin altına cümleler ve Markdown listeleri girebilirsiniz.

Ayrıntılı parametreler

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

HTML çıkışını incelemek için netdata yayınlama ön ekine bakın.

Markdown listeleri olan parametreler

Listeleri @cparam tarihinden sonra da kullanabilirsiniz. Bu, kullanılan komut bağımsız değişkenleri hakkında ayrıntılı bilgi vermek istediğinizde yararlı olur.

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

HTML çıkışını incelemek için netdata show bölümüne bakın.

@cli blok, boşluk içermeyen kesintisiz tek bir yorum olmalıdır. @cparam altına bir liste ekler, ardından bu listenin altına başka bir paragraf eklemeniz gerekirse listeyi manuel olarak sonlandırmak için . nokta kullanın.

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

Daha fazla örnek için Doxygen'in Lists (Listeler) bölümüne bakın.

#otFunctionName veya @sa ile diğer API yöntemlerine ya da işlevlerine bağlantı oluşturabilirsiniz. KSA yorum bloğunun sonuna bu bağlantıları girin.

/**
 * @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 bağlantıları, KSA ve API Referansları başlığında görüntülenir. HTML çıkışını incelemek için netdata yayınlama ön ekine bakın.

Bazen Doxygen, normal bir kelimeyi bir KSA sınıfının bağlantısı olarak karıştırabilir (örneğin, Joiner kelimesi). Doxygen'in cümlede kullanılan anahtar kelimelere veya sınıf adlarına bağlantı vermesini önlemek için kelimenin önünde % operatörünü kullanın. Örneğin:

Clear the %Joiner discerner

Daha fazla bilgi için Doksijen kılavuzundaki Otomatik bağlantı oluşturma bölümüne bakın.

Diğer komutlara bağlantı oluşturmak için @csa komutunu kullanın.

* @csa{netdata publish dnssrp anycast}

Bir komut aşırı yüklendiyse parantez ekleyin ve varsa virgül ekleyin. Parantez içinde boşluk kullanmayın:

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

Doxygen özel komutları

CLI komutları, aşağıdaki Doxygen ALIASES'i ve özel komutları destekler:

TAKMA AD Örnek Açıklama
@cli @cli ba bağlantı noktası Komut adı. KSA yorum bloğu başlatır.
@kod @code
ba bağlantı noktası
41953
Bitti
@endcode		 Komut örneği.
@ca [@ca{önek}] Komut bağımsız değişkeni. İsteğe bağlı bağımsız değişkenler için köşeli parantez [ ] kullanın.
@cparam @cparamjoiner discerner @ca{discerner}
Parametre ayrıntıları.		 Komut parametreleri.
@par @par
İsteğe bağlı KSA açıklaması.		 KSA'ya özel paragraflar.
@csa @csa{prefix add} Komut Ayrıca Bkz.. Başka bir komuta bağlantı verir.
@sa @sa otBorderRouterConfig Ayrıca bkz. Bir API Referansı'na bağlantı oluşturur.
@genel bakış @genel bakış OpenThread CLI'ye Genel Bakış için bağlantı oluşturur.
@netveri @netveri OT KSA ile Görüntülü Reklam Ağı Verilerini Yönetme ve Ağ Verilerini Yönetme bağlantısı oluşturur.
@veri kümesi @veri kümesi OT KSA ile Veri Kümelerini Görüntüleme ve Yönetme bağlantısı oluşturur.
@udp @udp OT CLI ile UDP İşlevini Test Etme bağlantısı oluşturur.
@ekbilgi @ekbilgi{@netdata} Tavsiye bağlantısı oluşturur.
@not @note Önemli açıklama metni. Not açıklama kutusu oluşturur.

make pretty komut dosyası tarafından kaybolan satırlar düzeltiliyor

CLI parametreleri veya komut çıkışı gibi bazı kod yorumlarının, Openthread.io referansında doğru şekilde oluşturulabilmesi için tek bir satırda olması gerekir. Bununla birlikte make pretty, uzun satırlar için oluşturulan çıkışı bozabilecek bir sütun genişliği sınırı uygular.

Bu durum, aşağıdaki iki örnekte gösterildiği gibi, satır sonları eklenerek ve satır sonları bir HTML açıklama etiketi ile kapatılarak ele alınabilir.

İlk örnek, en fazla altı parametre alabilen dns resolve komutudur. make pretty kontrolünü geçerken Doxygen kullanarak söz dizimini doğru şekilde oluşturmak için parametreler kaynakta üç satıra bölünmelidir:

* @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}]

İkinci örnek, history ipaddr list 5 komutunun çıkışıdır. Sonucun düzgün bir şekilde oluşturulması ve yine de make pretty kontrolünü geçmesi için beş çıkış satırının her biri aşağıdaki gibi iki satıra bölünmelidir:

* 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