อัปเดตคำสั่ง OT CLI

ดูซอร์สใน GitHub

เราสร้างคำสั่ง CLI จากไฟล์แหล่งที่มา CLI ในที่เก็บของ GitHub openthread

คู่มือนี้จะแสดงวิธีใช้ความคิดเห็น Doxygen ที่กำหนดเอง ที่เราใช้ในการสร้างรายการคำสั่ง

เริ่มต้นใช้งาน

ในการจัดทำเอกสารคำสั่ง CLI ให้ทำตามขั้นตอนต่อไปนี้ คุณต้องทำตามขั้นตอนเหล่านี้ ตามลำดับที่ให้ไว้

1. ค้นหา Cmd ที่เกี่ยวข้องจากไดเรกทอรี openthread/src/cli เช่น หากต้องการค้นหา ba state ให้ค้นหา Cmd("ba") แต่ละคำสั่งจะมีเทมเพลตฟังก์ชันที่เกี่ยวข้องกัน ดังนี้

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

2. ในเทมเพลตฟังก์ชัน ให้ค้นหาตรรกะคำสั่งที่ถูกต้อง เช่น ba state

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

3. ก่อนที่ตรรกะจะเริ่มขึ้น ให้เริ่มต้นบล็อก Doxygen ของ @cli:

   /**
    * @cli ba state
   

4. ถัดไป ด้านล่าง @cli เพิ่มตัวอย่างโดยใช้ @code ใส่ตัวอย่างอย่างน้อย 1 ตัวอย่าง อย่ารวมพรอมต์ > และอย่าลืมบันทึกผลลัพธ์ที่ส่งคืนทั้งหมด รวมถึงการตอบกลับ Done มาตรฐาน

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

เนื่องจากคำสั่ง CLI ให้สิทธิ์การเข้าถึงบรรทัดคำสั่งแก่เมธอดและฟังก์ชัน API ทั่วไป คำสั่งบางรายการจะมีคำอธิบายเดียวกันกับ API ที่เกี่ยวข้อง หากคำอธิบายคำสั่งเหมือนกัน ให้ทำตามขั้นตอนต่อไปนี้

1. ค้นหา API ที่เชื่อมโยงจากไดเรกทอรี openthread/include/openthread ตัวอย่างเช่น ba state จะจับคู่กับ otBorderAgentGetState

2. ใช้คำสั่ง 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 ตัวเลือก ดังนี้

1. เผยแพร่ตามที่อยู่และหมายเลขพอร์ต
2. เผยแพร่ตามหมายเลขพอร์ตและ 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