Mengupdate Perintah OT CLI

Lihat sumber di GitHub

Kita menghasilkan Perintah CLI dari file sumber CLI di thread terbuka repositori GitHub ASL.

Panduan ini memberikan petunjuk tentang cara menggunakan komentar Doxygen kustom kami yang kita gunakan untuk membuat daftar perintah.

Mulai

Untuk mendokumentasikan perintah CLI, selesaikan langkah-langkah berikut. Sangat penting bahwa Anda mengikuti langkah-langkah ini sesuai urutan yang ditentukan.

1. Menemukan Cmd terkait dari openthread/src/cli saat ini. Misalnya, untuk menemukan ba state, telusuri Cmd("ba"). Setiap perintah akan memiliki template fungsi terkait:

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

2. Di template fungsi, temukan logika perintah yang benar. Misalnya, ba state:

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

3. Sebelum logika dimulai, mulai blok Doksigen @cli:

   /**
    * @cli ba state
   

4. Selanjutnya, tepat di bawah @cli, tambahkan contoh menggunakan @code. Sertakan di setidaknya satu contoh. Jangan sertakan perintah >, dan pastikan untuk mendokumentasikan output hasil lengkap, termasuk respons Done standar.

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

Karena perintah CLI menyediakan akses command line ke metode API umum dan fungsi, beberapa perintah memiliki deskripsi yang sama dengan API yang sesuai. Jika deskripsi perintah sama, selesaikan langkah-langkah berikut:

1. Menemukan API terkait dari openthread/include/openthread saat ini. Misalnya, ba state dipetakan ke otBorderAgentGetState.

2. Gunakan perintah api_copy, lalu masukkan nama API tepat di bawahnya. Di depan definisi API, pastikan Anda menggunakan tanda pagar # untuk membuat tautan Doxygen otomatis.

   @par api_copy
   #otBorderAgentGetState
   

Berikut adalah contoh lengkap dari komentar Doksigen minimum yang diperlukan untuk membuat perintah OT CLI secara otomatis:

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

Untuk meninjau {i>output<i} HTML, lihat status ba. Untuk mengetahui contoh lanjutan dan opsi tambahan, lihat bagian berikut.

Opsi template CLI

Perintah CLI dikelompokkan oleh satu blok komentar berkelanjutan, dimulai dengan Tag ALIAS @cli. Beberapa contoh @code didukung.

Urutan Anda menentukan setiap tag adalah hal penting.

• @cparam harus diberikan setelah @code
• Jika Anda menyalin deskripsi API, @par api_copy harus disertakan setelahnya @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

Selanjutnya, pelajari lebih lanjut cara setiap tag ALIAS digunakan.

Nama perintah

Semua teks setelah @cli akan menjadi header nama perintah. {i>Header<i} ini digunakan di penautan dinamis, misalnya awalan publikasi netdata berikut:

 * @cli netdata publish prefix

Perintah lain mungkin lebih rumit. Misalnya, netdata publish dnssrp unicast menyediakan beberapa opsi:

1. Publikasikan menurut alamat dan nomor port
2. Memublikasikan menurut nomor port dan Mesh-Local EID perangkat

Jika perintah kelebihan beban, gunakan tanda kurung untuk mengidentifikasi perintah secara unik.

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

Deskripsi perintah

Ada tiga cara untuk mendokumentasikan deskripsi perintah. Anda dapat menyalin deskripsi API, gunakan deskripsi API tetapi tambahkan informasi tambahan, atau berikan deskripsi yang benar-benar unik yang hanya dimiliki oleh menggunakan perintah CLI. Di bagian berikutnya, kita akan membahas setiap metode.

Menyalin deskripsi API yang sesuai

Gunakan api_copy untuk menyalin metode atau fungsi API yang sesuai. Kapan menyalin API, pastikan deskripsinya berfungsi untuk melalui API, lalu perintah CLI. Hindari penggunaan frasa yang hanya berlaku untuk fungsi, misalnya This function atau This method. Lebih suka kalimat aktif, misalnya Gets the atau Sets the.

 * @par api_copy
 * #otBorderAgentGetState

Menambahkan informasi lainnya ke deskripsi API

Jika Anda ingin menggunakan api_copy tetapi perlu menambahkan informasi tambahan yang hanya berlaku untuk perintah CLI, gunakan @par. Setelah tag @par, pastikan untuk menurunkan ke baris berikutnya.

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

Paragraf ini ditampilkan setelah deskripsi API.

Hanya memberikan deskripsi khusus CLI

Beberapa perintah CLI menggunakan beberapa API, atau berbeda dengan panggilan API. API lainnya tidak memiliki API terkait, misalnya netdata help. Untuk memberikan deskripsi terpisah, gunakan @par. Jangan sertakan judul @par, dan mulai deskripsi Anda pada berikutnya garis. Dalam skenario ini, jangan gunakan @api_copy.

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

Parameter

Tentukan parameter perintah menggunakan @cparam dan @ca.

• Tempatkan tanda kurung [ ] di sekitar argumen opsional.
• Gunakan batang vertikal | (pipa) di antara pilihan argumen.
• Untuk menampilkan detail parameter, Anda dapat memasukkan kalimat dan daftar markdown di bawah tag @cparam.

Parameter dengan detail

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

Untuk meninjau output HTML, lihat awalan publikasi netdata.

Parameter dengan daftar markdown

Anda juga dapat menggunakan daftar setelah @cparam. Ini berguna saat Anda ingin menyediakan detail tentang argumen perintah yang digunakan.

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

Untuk meninjau output HTML, lihat acara netdata.

Blok @cli harus berupa satu komentar berkelanjutan tanpa spasi. Jika Anda menambahkan daftar di bawah @cparam, lalu memerlukan paragraf lain di bawah daftar tersebut, gunakan titik . untuk mengakhiri daftar secara manual.

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

Untuk contoh tambahan, lihat Daftar.

Menautkan API secara otomatis

Anda dapat menautkan ke metode atau fungsi API lainnya dengan #otFunctionName atau @sa. Masukkan tautan ini di akhir blok komentar CLI.

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

Link @sa ditampilkan dalam judul Referensi CLI dan API. Untuk meninjau HTML output, lihat awalan publikasi netdata.

Mencegah penautan otomatis

Kadang-kadang, Doxygen mungkin keliru mengartikan kata biasa sebagai tautan ke kelas CLI, contoh, kata Joiner. Untuk mencegah Doxygen menautkan ke kata kunci atau kelas digunakan dalam sebuah kalimat, gunakan operator % di depan kata, misalnya:

Clear the %Joiner discerner

Untuk informasi selengkapnya, lihat Pembuatan link otomatis dalam panduan Doxygen.

Menautkan secara otomatis ke perintah lain

Gunakan @csa untuk menautkan ke perintah lain.

* @csa{netdata publish dnssrp anycast}

Jika perintah kelebihan beban, sertakan tanda kurung dan tambahkan koma jika berlaku. Jangan menggunakan spasi di dalam tanda kurung:

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

Perintah khusus Doksigen

Perintah CLI mendukung Doxygen ALIASES dan perintah khusus berikut:

Memperbaiki baris yang rusak oleh skrip make pretty

Beberapa komentar kode, seperti parameter CLI atau output perintah, harus aktif baris tunggal bagi mereka untuk di-render dengan benar dalam referensi openthread.io. Namun, make pretty menerapkan batas lebar kolom, yang dapat merusak elemen yang dirender untuk baris panjang.

Situasi ini dapat diatasi dengan menambahkan baris baru dan menyertakannya dengan tag komentar HTML, seperti yang ditunjukkan pada dua contoh di bawah.

Contoh pertama adalah perintah dns resolve, yang bisa memakan waktu hingga enam parameter. Untuk merender sintaksis dengan benar menggunakan Doxygen sambil tetap meneruskan pemeriksaan make pretty, parameter harus dibagi menjadi tiga baris dalam sumber:

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

Contoh kedua adalah output dari perintah history ipaddr list 5. Agar output dirender dengan benar dan tetap lulus pemeriksaan make pretty, masing-masing dari lima baris {i>output<i} harus dibagi menjadi dua baris, sebagai berikut:

* 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