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

ดูแหล่งที่มาใน GitHub

เราสร้างคำสั่ง CLI จากไฟล์ต้นฉบับ CLI ใน openthread ที่เก็บ GitHub

คู่มือนี้จะแสดงวิธีใช้ความคิดเห็น 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. จากนั้น เพิ่มตัวอย่างโดยใช้ @code ใต้ @cli รวมที่ ตัวอย่างอย่างน้อย 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 โปรดดู bastate สำหรับตัวอย่างขั้นสูงและตัวเลือกอื่นๆ โปรดดูส่วนต่อไปนี้

ตัวเลือกเทมเพลต 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. เผยแพร่ตามหมายเลขพอร์ตและ EID ของ Mesh-Local ของอุปกรณ์

หากคำสั่งมีมากเกินไป ให้ใช้วงเล็บเพื่อระบุคำสั่งไม่ซ้ำกัน

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

การป้องกันการลิงก์อัตโนมัติ

บางครั้งด็อกซิเจนอาจเข้าใจผิดว่าคำปกติเป็นลิงก์ไปยังชั้นเรียน 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 และคำสั่งพิเศษต่อไปนี้

การแก้ไขบรรทัดที่ไม่ทำงานโดยสคริปต์ 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