เราสร้างคำสั่ง CLI จากไฟล์แหล่งที่มา CLI ในที่เก็บของ GitHub openthread
คู่มือนี้จะแสดงวิธีใช้ความคิดเห็น Doxygen ที่กำหนดเอง ที่เราใช้ในการสร้างรายการคำสั่ง
เริ่มต้นใช้งาน
ในการจัดทำเอกสารคำสั่ง CLI ให้ทำตามขั้นตอนต่อไปนี้ คุณต้องทำตามขั้นตอนเหล่านี้ ตามลำดับที่ให้ไว้
ค้นหา
Cmd
ที่เกี่ยวข้องจากไดเรกทอรีopenthread/src/cli
เช่น หากต้องการค้นหาba state
ให้ค้นหาCmd("ba")
แต่ละคำสั่งจะมีเทมเพลตฟังก์ชันที่เกี่ยวข้องกัน ดังนี้template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])
ในเทมเพลตฟังก์ชัน ให้ค้นหาตรรกะคำสั่งที่ถูกต้อง เช่น
ba state
else if (aArgs[0] == "state")
ก่อนที่ตรรกะจะเริ่มขึ้น ให้เริ่มต้นบล็อก Doxygen ของ
@cli
:/** * @cli ba state
ถัดไป ด้านล่าง
@cli
เพิ่มตัวอย่างโดยใช้@code
ใส่ตัวอย่างอย่างน้อย 1 ตัวอย่าง อย่ารวมพรอมต์>
และอย่าลืมบันทึกผลลัพธ์ที่ส่งคืนทั้งหมด รวมถึงการตอบกลับDone
มาตรฐาน* @code * ba state * Started * Done * @endcode
เนื่องจากคำสั่ง CLI ให้สิทธิ์การเข้าถึงบรรทัดคำสั่งแก่เมธอดและฟังก์ชัน API ทั่วไป คำสั่งบางรายการจะมีคำอธิบายเดียวกันกับ API ที่เกี่ยวข้อง หากคำอธิบายคำสั่งเหมือนกัน ให้ทำตามขั้นตอนต่อไปนี้
ค้นหา API ที่เชื่อมโยงจากไดเรกทอรี
openthread/include/openthread
ตัวอย่างเช่นba state
จะจับคู่กับotBorderAgentGetState
ใช้คำสั่ง
api_copy
แล้วป้อนชื่อ API ที่ด้านล่างโดยตรง ที่หน้าคำจำกัดความของ API ให้ใช้เครื่องหมายสี่เหลี่ยม#
เพื่อสร้างลิงก์ Doxygen อัตโนมัติ@par api_copy #otBorderAgentGetState
ต่อไปนี้คือตัวอย่างที่สมบูรณ์ของความคิดเห็นขั้นต่ำของ Doxygen ที่จำเป็นต่อการสร้างคำสั่ง OT CLI โดยอัตโนมัติ
/**
* @cli ba state
* @code
* ba state
* Started
* Done
* @endcode
* @par api_copy
* #otBorderAgentGetState
*/
หากต้องการตรวจสอบเอาต์พุต HTML โปรดดูสถานะ ba สำหรับตัวอย่างขั้นสูงและตัวเลือกเพิ่มเติม โปรดดูหัวข้อต่อไปนี้
ตัวเลือกเทมเพลต CLI
คำสั่ง CLI จะจัดกลุ่มตามบล็อกความคิดเห็นแบบต่อเนื่อง 1 บล็อก โดยขึ้นต้นด้วยแท็ก ALIAS @cli
ระบบรองรับตัวอย่าง @code
หลายรายการ
ลำดับที่คุณระบุแต่ละแท็กมีความสำคัญ
@cparam
ต้องอยู่หลัง@code
- หากคัดลอกคำอธิบาย API จะต้องระบุ
@par api_copy
ไว้หลัง@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
ถัดไป คือการดูข้อมูลเพิ่มเติมเกี่ยวกับวิธีใช้แท็ก ALIAS แต่ละรายการ
ชื่อคำสั่ง
ข้อความใดก็ตามที่อยู่หลัง @cli
จะกลายเป็นส่วนหัวของชื่อคำสั่ง ส่วนหัวนี้จะใช้ในการลิงก์แบบไดนามิก เช่น คำสั่ง
netdataยังคงเผยแพร่คำนำหน้า:
* @cli netdata publish prefix
คำสั่งอื่นๆ อาจซับซ้อนกว่า ตัวอย่างเช่น netdata publish dnssrp unicast
มีตัวเลือก 2-3 ตัวเลือก ดังนี้
- เผยแพร่ตามที่อยู่และหมายเลขพอร์ต
- เผยแพร่ตามหมายเลขพอร์ตและ Mesh-Local EID ของอุปกรณ์
หากคำสั่งทำงานหนักเกินไป ให้ใช้วงเล็บเพื่อระบุคำสั่งที่ไม่ซ้ำกัน
* @cli netdata publish dnssrp unicast (mle)
* @cli netdata publish dnssrp unicast (addr,port)
คำอธิบายคำสั่ง
การบันทึกคำอธิบายคำสั่งมี 3 วิธี คุณจะคัดลอกคำอธิบาย API ใช้คำอธิบาย API แต่เพิ่มข้อมูลเพิ่มเติม หรือใส่คำอธิบายที่ไม่ซ้ำโดยสิ้นเชิงซึ่งเป็นของคำสั่ง CLI เท่านั้นได้ ในส่วนถัดไป เราจะไปดูแต่ละวิธี
คัดลอกคำอธิบาย API ที่เกี่ยวข้อง
ใช้ api_copy
เพื่อคัดลอกเมธอดหรือฟังก์ชัน API ที่เกี่ยวข้อง เมื่อคุณคัดลอก API โปรดตรวจสอบว่าคำอธิบายใช้งานได้กับทั้ง API และคำสั่ง CLI หลีกเลี่ยงการใช้วลีที่มีผลกับฟังก์ชันเท่านั้น เช่น This function
หรือ This method
ต้องการใช้รูปประโยคที่ประธานเป็นผู้กระทำ เช่น Gets the
หรือ Sets the
* @par api_copy
* #otBorderAgentGetState
ใส่ข้อมูลเพิ่มเติมลงในคำอธิบาย API
หากคุณต้องการใช้ api_copy
แต่ต้องการเพิ่มข้อมูลเพิ่มเติมที่ใช้กับคำสั่ง CLI เท่านั้น ให้ใช้ @par
หลังจากแท็ก @par
อย่าลืมเลื่อนลงไปที่บรรทัดถัดไป
* @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.
ย่อหน้าเหล่านี้จะแสดงหลังคำอธิบาย API
ระบุคำอธิบายสำหรับ CLI โดยเฉพาะเท่านั้น
คำสั่ง CLI บางคำสั่งใช้ API หลายตัว หรือแตกต่างจากการเรียก API
แต่แอปอื่นๆ ไม่มี API ที่เชื่อมโยง เช่น netdata help
หากต้องการใส่คำอธิบายแยกต่างหาก ให้ใช้ @par
อย่าใส่ชื่อ @par
และขึ้นต้นคำอธิบายในบรรทัดถัดไป ในสถานการณ์นี้ อย่าใช้ @api_copy
/**
* @cli netdata help
* @code
* netdata help
* ...
* show
* steeringdata
* unpublish
* Done
* @endcode
* @par
* Gets a list of `netdata` CLI commands.
*/
พารามิเตอร์
กำหนดพารามิเตอร์คำสั่งโดยใช้ @cparam
และ @ca
- ใส่วงเล็บเหลี่ยม
[ ]
ล้อมรอบอาร์กิวเมนต์ที่ไม่บังคับ - ใช้แถบแนวตั้ง
|
(ขีดตั้ง) ระหว่างตัวเลือกอาร์กิวเมนต์ - หากต้องการแสดงรายละเอียดพารามิเตอร์ ให้ป้อนประโยคและรายการมาร์กดาวน์ใต้แท็ก
@cparam
พารามิเตอร์พร้อมรายละเอียด
* @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 โปรดดูคำนำหน้าการเผยแพร่ Netdata
พารามิเตอร์ที่มีรายการมาร์กดาวน์
คุณยังใช้รายการหลังวันที่ @cparam
ได้อีกด้วย ซึ่งจะเป็นประโยชน์เมื่อคุณต้องการระบุรายละเอียดเกี่ยวกับอาร์กิวเมนต์คำสั่งที่ใช้
* @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 โปรดดู netdata show
การบล็อก @cli
ต้องเป็นความคิดเห็นที่ต่อเนื่อง 1 รายการโดยไม่มีการเว้นวรรค หากคุณเพิ่มรายการด้านล่าง @cparam
และต้องการย่อหน้าอื่นใต้รายการนั้น ให้ใช้จุด .
เพื่อสิ้นสุดรายการด้วยตนเอง
* @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.
ดูตัวอย่างเพิ่มเติมได้ที่ลิสต์ของ Doxygen
ลิงก์ API โดยอัตโนมัติ
คุณสามารถลิงก์ไปยังเมธอดหรือฟังก์ชัน API อื่นๆ ด้วย #otFunctionName
หรือ @sa
ป้อนลิงก์เหล่านี้ที่ส่วนท้ายของส่วนความคิดเห็น 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
*/
ลิงก์ @sa
จะแสดงอยู่ในหัวข้อการอ้างอิง CLI และ API หากต้องการตรวจสอบเอาต์พุต HTML
โปรดดูคำนำหน้าการเผยแพร่ Netdata
การป้องกันลิงก์อัตโนมัติ
บางครั้ง Doxygen อาจเข้าใจผิดว่าคำปกติเป็นลิงก์ไปยังคลาส CLI เช่น คำว่า Joiner
หากต้องการป้องกันไม่ให้ Doxygen ลิงก์ไปยังคีย์เวิร์ดหรือชื่อคลาสที่ใช้ในประโยค ให้ใช้โอเปอเรเตอร์ %
หน้าคํานั้น เช่น
Clear the %Joiner discerner
ดูข้อมูลเพิ่มเติมได้ที่การสร้างลิงก์อัตโนมัติในคู่มือของ Doxygen
ลิงก์กับคำสั่งอื่นๆ โดยอัตโนมัติ
ใช้ @csa
เพื่อลิงก์กับคำสั่งอื่นๆ
* @csa{netdata publish dnssrp anycast}
หากคำสั่งมากเกินไป ให้ใส่วงเล็บและเพิ่มเครื่องหมายจุลภาค (หากมี) อย่าใช้ช่องว่างภายในวงเล็บ
* @csa{netdata publish dnssrp unicast (addr,port)}
* @csa{netdata publish dnssrp unicast (mle)}
คำสั่งพิเศษของ Doxygen
คำสั่ง CLI รองรับ Doxygen ALIASES และคำสั่งพิเศษต่อไปนี้
ชื่อแทน | ตัวอย่าง | คำอธิบาย |
---|---|---|
@cli | พอร์ต @cli ba | ชื่อคำสั่ง เริ่มบล็อกความคิดเห็น CLI |
@รหัส | พอร์ต @code ba 41953 เสร็จสิ้น @endcode |
ตัวอย่างคำสั่ง |
@ca | [@ca{prefix}] | อาร์กิวเมนต์คำสั่ง ใช้วงเล็บ [ ] สำหรับอาร์กิวเมนต์ที่ไม่บังคับ |
@cparam | @cparamjoiner diserner @ca{discerner} รายละเอียดพารามิเตอร์ |
พารามิเตอร์คำสั่ง |
@par | @par คำอธิบาย CLI ที่ไม่บังคับ |
ย่อหน้าเฉพาะ CLI |
@csa | @csa{prefix add} | คำสั่ง "ดูเพิ่มเติม" ลิงก์ไปยังคำสั่งอื่น |
@sa | @sa otBorderRouterConfig | ดูเพิ่มเติม สร้างลิงก์ไปยังเอกสารอ้างอิง API |
@ภาพรวม | @ภาพรวม | สร้างลิงก์ไปยังภาพรวม CLI ของ OpenThread |
@เน็ต | @เน็ต | สร้างลิงก์ไปยังแสดงและจัดการข้อมูลเครือข่ายด้วย OT CLI |
@ชุดข้อมูล | @ชุดข้อมูล | สร้างลิงก์ไปยังแสดงและจัดการชุดข้อมูลด้วย OT CLI |
@udp | @udp | สร้างลิงก์เพื่อทดสอบฟังก์ชัน UDP ด้วย OT CLI |
@moreinfo | @moreinfo{@netdata} | สร้างลิงก์สำหรับแนะนำบอกต่อ |
@หมายเหตุ | @note ข้อความสำคัญ | สร้างกล่องข้อความเสริมของโน้ต |
การแก้ไขบรรทัดที่สคริปต์ make pretty
เสียหาย
ความคิดเห็นเกี่ยวกับโค้ดบางรายการ เช่น พารามิเตอร์ CLI หรือเอาต์พุตคำสั่ง ต้องอยู่ในบรรทัดเดียวเพื่อให้แสดงผลอย่างถูกต้องในการอ้างอิง openthread.io
อย่างไรก็ตาม make pretty
จะกำหนดความกว้างของคอลัมน์ ซึ่งอาจส่งผลให้เอาต์พุตที่แสดงผลสำหรับบรรทัดยาวๆ เสียหายได้
สถานการณ์นี้สามารถแก้ไขได้โดยการเพิ่มตัวแบ่งบรรทัดและล้อมรอบ แท็กด้วยแท็กความคิดเห็น HTML ดังที่แสดงใน 2 ตัวอย่างด้านล่าง
ตัวอย่างแรกคือคำสั่ง dns resolve
ซึ่งสามารถมีพารามิเตอร์ได้สูงสุด 6 รายการ หากต้องการแสดงผลไวยากรณ์อย่างถูกต้องโดยใช้ Doxygen ขณะที่ยังผ่านการตรวจสอบ make pretty
อยู่ จะต้องแยกพารามิเตอร์ออกเป็น 3 บรรทัดในต้นฉบับ ดังนี้
* @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}]
ตัวอย่างที่ 2 เป็นเอาต์พุตของคำสั่ง history ipaddr list 5
เพื่อให้เอาต์พุตแสดงอย่างถูกต้องและยังคงผ่านการตรวจสอบ make pretty
เอาต์พุต 5 บรรทัดต้องแบ่งออกเป็น 2 บรรทัด ดังนี้
* 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