Mengupdate Perintah OT CLI

Lihat sumber di GitHub

Kita menghasilkan Perintah CLI dari file sumber CLI di repositori GitHub openthread.

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

Mulai

Untuk mendokumentasikan perintah CLI, selesaikan langkah-langkah berikut. Anda harus mengikuti langkah-langkah ini sesuai urutan yang diberikan.

  1. Temukan Cmd terkait dari direktori openthread/src/cli. 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 Doxygen @cli:

    /**
 * @cli ba state

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

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

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

  1. Temukan API terkait dari direktori openthread/include/openthread. Misalnya, ba state dipetakan ke otBorderAgentGetState.

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

    @par api_copy
#otBorderAgentGetState

Berikut adalah contoh lengkap komentar Doxygen 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 output HTML, lihat status ba. Untuk contoh lanjutan dan opsi tambahan, lihat bagian berikut.

Opsi template CLI

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

Urutan yang Anda tentukan untuk setiap tag penting.

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

Teks apa pun setelah @cli menjadi header nama perintah. Header ini digunakan dalam penautan dinamis, misalnya perintah netdata publish publish:

 * @cli netdata publish prefix

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

  1. Memublikasikan menurut alamat dan nomor port
  2. Memublikasikan menurut nomor port dan EID Mesh-Lokal 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, menggunakan deskripsi API, tetapi menambahkan informasi tambahan, atau memberikan deskripsi yang benar-benar unik yang hanya dimiliki oleh perintah CLI. Di bagian berikutnya, kita akan membahas setiap metode.

Salin deskripsi API yang sesuai

Gunakan api_copy untuk menyalin metode atau fungsi API yang sesuai. Saat Anda menyalin API, pastikan deskripsi akan berfungsi untuk perintah API maupun CLI. Hindari penggunaan frasa yang hanya berlaku untuk suatu fungsi, misalnya This function atau This method. Pilih 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 drop-down 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 berikan deskripsi khusus CLI

Beberapa perintah CLI menggunakan beberapa API, atau berbeda dengan panggilan API. Beberapa domain lainnya tidak memiliki API terkait, misalnya netdata help. Untuk memberikan deskripsi terpisah, gunakan @par. Jangan sertakan judul @par, dan mulai deskripsi Anda di baris berikutnya. 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

Menentukan 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 detailnya

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

Anda dapat menautkan ke metode atau fungsi API lainnya dengan #otFunctionName atau @sa. Masukkan link 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 output HTML, lihat awalan publikasi netdata.

Terkadang, Doxygen mungkin salah menganggap kata biasa sebagai link ke class CLI, misalnya, kata Joiner. Agar Doxygen tidak ditautkan ke kata kunci atau nama class yang digunakan dalam kalimat, gunakan operator % di depan kata tersebut, misalnya:

Clear the %Joiner discerner

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

Gunakan @csa untuk menautkan ke perintah lain.

* @csa{netdata publish dnssrp anycast}

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

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

Perintah khusus doxygen

Perintah CLI mendukung ALIASES Doxygen dan perintah khusus berikut:

ALIAS Contoh Deskripsi
@cli Port @cli ba Nama perintah. Memulai blok komentar CLI.
@kode @code
port ba
41953
Selesai
@endcode		 Contoh perintah.
@ca [@ca{prefix}] Argumen perintah. Gunakan tanda kurung [ ] untuk argumen opsional.
@cparam @cparam joiner discerner @ca{discerner}
Detail parameter.		 Parameter perintah.
@par @par
Deskripsi CLI opsional.		 Paragraf khusus CLI.
@csa @csa{prefix add} Perintah Lihat Juga. Menautkan ke perintah lain.
@sa @sa otBorderRouterConfig Lihat Juga. Membuat link ke Referensi API.
@ringkasan @ringkasan Membuat link ke Ringkasan CLI OpenThread.
@netdata @netdata Membuat link ke Menampilkan dan Mengelola Data Jaringan dengan OT CLI.
@set data @set data Membuat link ke Menampilkan dan Mengelola Set Data dengan OT CLI.
@udp @udp Membuat link ke Menguji Fungsi UDP dengan OT CLI.
@infoselengkapnya @moreinfo{@netdata} Membuat link rujukan.
@catatan @note Info penting. Membuat kotak info catatan.

Memperbaiki baris yang rusak oleh skrip make pretty

Beberapa komentar kode, seperti parameter CLI atau output perintah, harus berada dalam satu baris agar dapat dirender dengan benar dalam referensi openthread.io. Namun, make pretty menerapkan batas lebar kolom, yang dapat merusak output yang dirender untuk baris yang panjang.

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

Contoh pertama adalah perintah dns resolve, yang dapat menggunakan hingga enam parameter. Untuk merender sintaksis dengan benar menggunakan Doxygen sambil tetap lulus pemeriksaan make pretty, parameter harus dibagi menjadi tiga baris di 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 perintah history ipaddr list 5. Agar output dirender dengan benar dan tetap lulus pemeriksaan make pretty, masing-masing dari lima baris output 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