Cập nhật lệnh OT CLI

Xem nguồn trên GitHub

Chúng tôi tạo Lệnh CLI từ các tệp nguồn CLI trong kho lưu trữ GitHub openthread.

Hướng dẫn này đưa ra cách sử dụng nhận xét Doxygen tuỳ chỉnh mà chúng tôi dùng để tạo danh sách lệnh.

Bắt đầu

Để ghi lại một lệnh CLI, hãy hoàn tất các bước sau. Bạn phải làm theo các bước này theo thứ tự được cung cấp.

1. Tìm Cmd được liên kết trong thư mục openthread/src/cli. Ví dụ: để tìm ba state, hãy tìm kiếm Cmd("ba"). Mỗi lệnh sẽ có một mẫu hàm được liên kết:

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

2. Trong mẫu hàm, hãy tìm logic lệnh chính xác. Ví dụ như ba state:

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

3. Trước khi logic bắt đầu, hãy khởi động khối Doxygen @cli:

   /**
    * @cli ba state
   

4. Tiếp theo, ngay bên dưới @cli, hãy thêm các ví dụ bằng @code. Hãy đưa vào ít nhất một ví dụ. Đừng đưa vào lời nhắc > và nhớ ghi lại toàn bộ kết quả trả về, bao gồm cả phản hồi Done chuẩn.

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

Do các lệnh CLI cung cấp quyền truy cập dòng lệnh vào các phương thức và hàm API phổ biến, nên một số lệnh có cùng nội dung mô tả với API tương ứng. Nếu nội dung mô tả lệnh giống nhau, hãy hoàn thành các bước sau:

1. Tìm API được liên kết trong thư mục openthread/include/openthread. Ví dụ: ba state ánh xạ tới otBorderAgentGetState.

2. Dùng lệnh api_copy, sau đó nhập tên API ngay bên dưới. Trước định nghĩa API, hãy nhớ sử dụng ký hiệu bảng Anh # để tạo đường liên kết Doxygen tự động.

   @par api_copy
   #otBorderAgentGetState
   

Dưới đây là một ví dụ hoàn chỉnh về các ghi chú Doxygen tối thiểu cần có để tự động tạo lệnh OT CLI:

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

Để xem lại kết quả HTML, hãy tham khảo trạng thái ba. Để xem ví dụ nâng cao và các lựa chọn bổ sung, hãy tham khảo các phần sau.

Lựa chọn mẫu CLI

Các lệnh CLI được nhóm theo một khối nhận xét liên tục, bắt đầu bằng thẻ ALIAS @cli. Nhiều ví dụ về @code được hỗ trợ.

Thứ tự bạn chỉ định cho mỗi thẻ là rất quan trọng.

• @cparam phải sau @code
• Nếu bạn sao chép phần mô tả API, @par api_copy phải đứng sau @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

Tiếp theo, hãy tìm hiểu thêm về cách sử dụng từng thẻ ALIAS.

Tên lệnh

Mọi văn bản sau @cli sẽ trở thành tiêu đề tên lệnh. Tiêu đề này được dùng trong tính năng liên kết động, ví dụ: lệnh netdata publish Currency (tiền tố phát hành netdata):

 * @cli netdata publish prefix

Các lệnh khác có thể phức tạp hơn. Ví dụ: netdata publish dnssrp unicast cung cấp một vài tuỳ chọn:

1. Xuất bản theo địa chỉ và số cổng
2. Phát hành theo số cổng và EID cục bộ (Mesh-Local) của thiết bị

Nếu một lệnh bị nạp chồng, hãy dùng dấu ngoặc đơn để xác định riêng lệnh đó.

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

Mô tả lệnh

Có 3 cách để ghi lại phần mô tả lệnh. Bạn có thể sao chép nội dung mô tả API, sử dụng nội dung mô tả API nhưng bổ sung thêm thông tin hoặc cung cấp nội dung mô tả hoàn toàn độc đáo chỉ thuộc về lệnh CLI. Trong phần tiếp theo, chúng ta sẽ tìm hiểu từng phương pháp.

Sao chép nội dung mô tả API tương ứng

Sử dụng api_copy để sao chép phương thức hoặc hàm API tương ứng. Khi sao chép API, hãy đảm bảo rằng nội dung mô tả sẽ phù hợp với cả API và lệnh CLI. Tránh sử dụng các cụm từ chỉ áp dụng cho một hàm, ví dụ: This function hoặc This method. Ưu tiên một giọng nói chủ động, ví dụ: Gets the hoặc Sets the.

 * @par api_copy
 * #otBorderAgentGetState

Bổ sung thông tin vào phần mô tả API

Nếu bạn muốn sử dụng api_copy nhưng cần thêm thông tin bổ sung chỉ áp dụng cho lệnh CLI, hãy sử dụng @par. Sau thẻ @par, hãy nhớ thả xuống dòng tiếp theo.

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

Các đoạn này sẽ xuất hiện sau phần mô tả API.

Chỉ cung cấp nội dung mô tả theo CLI cụ thể

Một số lệnh CLI sử dụng nhiều API hoặc khác với lệnh gọi API. Những ứng dụng khác thì không có API liên kết, ví dụ như netdata help. Để cung cấp nội dung mô tả riêng, hãy sử dụng @par. Đừng thêm tiêu đề @par và hãy bắt đầu nội dung mô tả ở dòng tiếp theo. Trong trường hợp này, đừng sử dụng @api_copy.

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

Tham số

Xác định các tham số lệnh bằng cách sử dụng @cparam và @ca.

• Đặt đối số không bắt buộc trong dấu ngoặc [ ].
• Sử dụng thanh dọc | (dấu sổ thẳng) giữa các lựa chọn đối số.
• Để hiển thị thông tin chi tiết về tham số, bạn có thể nhập câu và danh sách đánh dấu bên dưới thẻ @cparam.

Những thông số có thông tin chi tiết

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

Để xem lại kết quả HTML, hãy tham khảo tiền tố xuất bản netdata.

Thông số có danh sách Markdown

Bạn cũng có thể sử dụng danh sách sau @cparam. Điều này rất hữu ích khi bạn muốn cung cấp thông tin chi tiết về các đối số lệnh được sử dụng.

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

Để xem lại kết quả HTML, hãy tham khảo chương trình dữ liệu net.

Khối @cli phải là một nhận xét liên tục không có dấu cách. Nếu bạn thêm một danh sách bên dưới @cparam và sau đó cần một đoạn khác bên dưới danh sách đó, hãy sử dụng dấu chấm . để kết thúc danh sách theo cách thủ công.

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

Để biết thêm ví dụ, hãy tham khảo Danh sách của Doxygen.

Tự động liên kết API

Bạn có thể liên kết đến các phương thức hoặc hàm API khác bằng #otFunctionName hoặc @sa. Nhập các liên kết này vào cuối khối nhận xét 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
 */

Các đường liên kết @sa sẽ xuất hiện trong tiêu đề CLI và Tài liệu tham khảo API. Để xem lại kết quả HTML, hãy tham khảo tiền tố xuất bản netdata.

Ngăn chặn đường liên kết tự động

Đôi khi, Doxygen có thể nhầm một từ thông thường là đường liên kết đến một lớp CLI, chẳng hạn như từ Joiner. Để ngăn Doxygen liên kết đến các từ khoá hoặc tên lớp được dùng trong một câu, hãy sử dụng toán tử % ở trước từ đó, ví dụ:

Clear the %Joiner discerner

Để biết thêm thông tin, hãy tham khảo phần Tạo đường liên kết tự động trong hướng dẫn Doxygen.

Tự động liên kết với các lệnh khác

Dùng @csa để liên kết đến các lệnh khác.

* @csa{netdata publish dnssrp anycast}

Nếu một lệnh có trạng thái quá tải, hãy thêm dấu ngoặc đơn và thêm dấu phẩy (nếu có). Không sử dụng dấu cách trong dấu ngoặc đơn:

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

Lệnh đặc biệt của Doxygen

Các lệnh CLI hỗ trợ các Doxygen ALIASES và các lệnh đặc biệt sau đây:

BIỆT HIỆU	Ví dụ:	Nội dung mô tả
@cli	@cli ba cổng	Tên lệnh. Bắt đầu khối nhận xét CLI.
Mã @	@code cổng ba 41953 Xong @endcode	Ví dụ về lệnh.
@ca	[@ca{prefix}]	Đối số lệnh. Sử dụng dấu ngoặc [ ] cho các đối số không bắt buộc.
@cparam	@cparam joiner Discerner @ca{discerner} Thông tin chi tiết về tham số.	Tham số lệnh.
@par	@par Nội dung mô tả CLI không bắt buộc.	Đoạn văn bản cụ thể trong CLI.
@csa	@csa{prefix add}	Command Xem thêm. Liên kết đến một lệnh khác.
@sa	@sa otBorderRouterConfig	Xem thêm. Tạo đường liên kết đến một Tài liệu tham khảo API.
@tổng quan	@tổng quan	Tạo một đường liên kết đến OpenThread CLI Overview (Tổng quan về OpenThread CLI).
@netdata	@netdata	Tạo đường liên kết đến Hiển thị và quản lý dữ liệu mạng bằng OT CLI.
@tập dữ liệu	@tập dữ liệu	Tạo đường liên kết đến Hiển thị và quản lý tập dữ liệu bằng OT CLI.
@udp	@udp	Tạo một đường liên kết đến Kiểm thử chức năng UDP bằng OT CLI.
@moreinfo	@moreinfo{@netdata}	Tạo đường liên kết giới thiệu.
@ghi chú	@note Chú thích quan trọng.	Tạo hộp chú thích ghi chú.

Sửa các dòng bị hỏng do tập lệnh make pretty

Một số nhận xét về mã, chẳng hạn như tham số CLI hoặc dữ liệu đầu ra của lệnh, phải nằm trên một dòng để chúng hiển thị chính xác trong tệp tham chiếu openthread.io. Tuy nhiên, make pretty áp dụng giới hạn chiều rộng của cột, điều này có thể phá vỡ kết quả hiển thị đối với các dòng dài.

Bạn có thể giải quyết trường hợp này bằng cách thêm dấu ngắt dòng và đặt chúng bằng một thẻ nhận xét HTML, như minh hoạ trong 2 ví dụ bên dưới.

Ví dụ đầu tiên là lệnh dns resolve, có thể có tối đa 6 tham số. Để kết xuất đúng cú pháp bằng Doxygen mà vẫn vượt qua bước kiểm tra make pretty, các tham số phải được chia thành 3 dòng trong nguồn:

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

Ví dụ thứ hai là kết quả của lệnh history ipaddr list 5. Để kết quả hiển thị chính xác và vẫn vượt qua được việc kiểm tra make pretty, mỗi trong số 5 dòng đầu ra phải được chia thành hai dòng như sau:

* 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