OT CLI Komutlarını Güncelleme

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

CLI komutları oluştururuz CLI kaynak dosyalarından openthread GitHub deposu.

Bu kılavuzda, özel Doxsijen yorumlarımızın nasıl kullanılacağıyla ilgili talimatlar sunulmaktadır komut listesini oluştururuz.

Başlayın

Bir CLI komutunu belgelemek için aşağıdaki adımları tamamlayın. Kendinizi bu adımları verilen sırada uygularsınız.

1. openthread/src/cli içinde ilişkili Cmd öğesini bulun dizin. Örneğin, ba state öğesini bulmak için Cmd("ba") araması yapın. Her komutun ilişkilendirilmiş 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 bloğunu başlatın:

   /**
    * @cli ba state
   

4. Ardından, @cli öğesinin hemen altına @code kullanarak örnekler ekleyin. Dahil et: olmalıdır. > istemini eklemeyin ve standart Done yanıtı dahil olmak üzere tam dönüş çıkışını belgeleyin.

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

CLI komutları, yaygın API yöntemlerine komut satırı erişimi sağladığı için içeren bir komut dosyası kullanıyorsanız, bazı komutların tanımı Google Analytics 360'a ihtiyacınız olacaktır. Komut açıklaması aynıysa şu adımları uygulayın:

1. openthread/include/openthread üzerinden ilişkili API'yi bulun dizin. Örneğin, ba state, otBorderAgentGetState ile eşlenir.

2. api_copy komutunu kullanın, ardından doğrudan komutun altına API adını girin. API tanımının önünde pound işaretini # kullandığınızdan emin olun otomatik Doxygen bağlantısını oluşturun.

   @par api_copy
   #otBorderAgentGetState
   

Aşağıdaki örnekte, hesabınızdaki doxsijen yorumlarının doğru bir şekilde otomatik olarak bir OT CLI komutu oluşturur:

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

HTML çıkışını incelemek için şuraya bakın: ba eyalet'e gidin. Gelişmiş örnekler ve ek seçenekler için aşağıdaki bölümlere bakın.

CLI şablonu seçenekleri

CLI komutları, ALIAS etiketi @cli. Birden çok @code örneği desteklenir.

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

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

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

Komut adları

@cli ifadesinden sonraki tüm metinler komut adı başlığı haline gelir. Bu başlık şurada kullanılıyor: dinamik bağlantıdır. Örneğin netdata publish ön eki komut:

 * @cli netdata publish prefix

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

1. Adrese ve bağlantı noktası numarasına göre yayınla
2. Bağlantı noktası numarasına ve cihazın yerel ağ-yerel SIM kimliğine göre yayınlayın

Bir komut aşırı yüklenirse komutu benzersiz ş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. Google Etiket Yöneticisi'ni kullanarak API açıklamasını kullanın, API açıklamasını kullanın, ancak ek bilgi ekleyin, veya yalnızca CLI komutu gerekir. Sonraki bölümlerde bu yöntemlerin her birine değineceğiz.

İlgili API açıklamasını kopyalayın

İlgili API yöntemini veya işlevini kopyalamak için api_copy kullanın. Zaman API'leri kopyalamazsanız açıklamanın hem API ve CLI komutu. Yalnızca bir işlevini kullanın. Örneğin, This function veya This method. Tercih etkin bir ses (örneğin, Gets the veya Sets the).

 * @par api_copy
 * #otBorderAgentGetState

API açıklamasına daha fazla bilgi ekleyin

api_copy kullanmak istiyorsanız, ancak yalnızca CLI komutu için geçerlidir; @par kullanın. @par etiketinden sonra, tuşuna basarak bir sonraki satıra geçebilirsiniz.

 * @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örüntülenir.

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

Bazı CLI komutları birden fazla API kullanır veya API çağrısından farklıdır. Diğerlerinin ilişkili bir API'si yoktur (ör. netdata help). Ayrı bir açıklama girmek için @par özelliğini kullanın. @par başlık eklemeyin, açıklamanıza sonraki başlıkta başlayın satırında görünür. 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 önüne, [ ] 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 cümleler ve Markdown listeleri girebilirsiniz @cparam etiketinin altında.

Ayrıntıları içeren 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 publish ön ekine bakın.

Markdown listeleri olan parametreler

Listeleri @cparam tarihinden sonra da kullanabilirsiniz. Bu size zaman zaman kullanılan komut bağımsız değişkenleri hakkında ayrıntılı bilgi sağlar.

 * @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 adımına bakın.

@cli blok, boşluk içermeyen sürekli tek bir yorum olmalıdır. Örneğin @cparam altında bir listeye sahipseniz ve bu listenin altında başka bir paragrafa ihtiyaç duyuyorsanız listeyi manuel olarak sonlandırmak için bir nokta . kullanabilirsiniz.

* @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's Listeler.

API'leri otomatik olarak bağlama

Diğer API yöntemlerine veya işlevlerine #otFunctionName ya da @sa. 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'yi incelemek için çıkış, bkz. netdata publish öneki.

Otomatik bağlantıları engelleme

Doxsijen bazen normal bir kelimeyi, CLI sınıfına bir bağlantıyla karıştırabilir. örnek olarak Joiner kelimesi kullanılabilir. Doxygen'in anahtar kelimelere veya sınıfa bağlanmasını önlemek için bir cümlede kullanılan adlarda % operatörünü kullanın. örneğin:

Clear the %Joiner discerner

Daha fazla bilgi için: Otomatik bağlantı oluşturma yazın.

Diğer komutlara otomatik olarak bağlan

Diğer komutlara bağlanmak için @csa komutunu kullanın.

* @csa{netdata publish dnssrp anycast}

Bir komut aşırı yüklendiyse parantez ve virgül ekleyin (geçerli durumlarda) 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 ve özel komutları destekler:

make pretty komut dosyası tarafından bölünen satırları düzeltme

CLI parametreleri veya komut çıkışı gibi bazı kod yorumları açık olmalıdır Openthread.io referansında doğru şekilde oluşturulmaları için tek bir satır ekler. Ancak make pretty, sütun genişliği sınırı uygular. Bu da, oluşturulan uzun satırlar için bir çıkış noktası olabilir.

Bu durum satır sonları eklenerek ve satır içine alarak yapılabilir. aşağıdaki iki örnekte gösterildiği gibi, bir HTML yorum etiketi ile değiştirin.

İlk örnek dns resolve komutudur. Bu komutun tamamlanması altıya kadar sürebilir. parametreleridir. İletirken Doxygen'i kullanarak söz dizimini doğru bir şekilde oluşturmak için make pretty kontrolünde, parametrelerin üç satıra bölünmesi gerekir kaynak:

* @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. Çıkışın düzgün bir şekilde oluşturulması ve 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