Cập nhật lệnh OT CLI

Xem nguồn trên GitHub

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

Bài viết này hướng dẫn cách sử dụng các chú thích Doxygen tuỳ chỉnh của chúng tôi mà chúng tôi sử dụng để tạo danh sách lệnh.

Bắt đầu

Để ghi lại lệnh CLI, hãy hoàn tất các bước sau. Điều quan trọng là bạn 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 từ openthread/src/cli thư mục. 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 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. Bao gồm tại ít nhất một ví dụ. Đừng đưa lời nhắc > vào và hãy nhớ ghi lại kết quả trả về đầy đủ, bao gồm cả phản hồi Done tiêu chuẩn.

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

Vì 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 API phổ biến và hàm, 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 tất các bước sau:

  1. Tìm API được liên kết qua openthread/include/openthread thư mục. 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 phần định nghĩa API, hãy nhớ sử dụng ký hiệu bảng Anh # để tạo liên kết Doxygen tự động.

    @par api_copy
#otBorderAgentGetState

Sau đây là ví dụ hoàn chỉnh về số nhận xét Doxygen tối thiểu cần thiết để tự động tạo một lệnh OT CLI:

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

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

Tuỳ chọn mẫu CLI

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

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

  • @cparam phải đứng sau @code
  • Nếu bạn sao chép nội dung mô tả API, thì @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 sử dụng trong Liên kết động, ví dụ: tiền tố xuất bản 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 số tuỳ chọn:

  1. Xuất bản theo địa chỉ và số cổng
  2. Xuất bản theo số cổng và EID lưới cục bộ của thiết bị

Nếu một lệnh bị quá tải, hãy sử dụng dấu ngoặc đơn để nhận dạng duy nhất lệnh đó.

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

Mô tả lệnh

Có ba cách để ghi lại nội dung mô tả lệnh. Bạn có thể sao chép Mô tả API, sử dụng mô tả API nhưng thêm thông tin bổ sung, hoặc cung cấp một nội dung mô tả hoàn toàn độc đáo chỉ thuộc về Lệnh CLI. Trong các phần tiếp theo, chúng ta sẽ tìm hiểu về 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. Thời gian bạn 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 , ví dụ: This function hoặc This method. Ưu tiên một giọng nói đang hoạt động, ví dụ như Gets the hoặc Sets the.

 * @par api_copy
 * #otBorderAgentGetState

Thêm thông tin khác vào nội dung 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 dùng @par. Sau thẻ @par, hãy đảm bảo để 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 xuất hiện sau nội dung mô tả API.

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

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 mã khác không có API liên kết, ví dụ: netdata help. Để cung cấp nội dung mô tả riêng, hãy sử dụng @par. Đừng thêm tiêu đề @par mà hãy bắt đầu nội dung mô tả ở phần tiếp theo . Trong trường hợp này, khô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 @cparam và @ca.

  • Đặt dấu ngoặc [ ] quanh đối số không bắt buộ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ề thông số, bạn có thể nhập câu và danh sách Markdown bên dưới thẻ @cparam.

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 dữ liệu đầu ra 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 các 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 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 dữ liệu đầu ra HTML, hãy tham khảo netdata show.

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, 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.

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

Bạn có thể liên kết với 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
 */

Đường liên kết @sa hiển thị trong tiêu đề Tài liệu tham khảo CLI và API. Để xem lại HTML đầu ra, tham chiếu đến tiền tố xuất bản netdata.

Đôi khi, Doxygen có thể nhầm lẫn một từ bình thường là một đường liên kết đến lớp CLI, vì ví dụ: từ Joiner. Để ngăn Doxygen liên kết với các từ khoá hoặc lớp học tên 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 Tự động tạo đường liên kết trong hướng dẫn Doxygen.

Sử 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 bị 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)}

Các lệnh đặc biệt của Doxygen

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

BIỆT HIỆU Ví dụ: Mô tả
@cli @cli ba cổng Tên lệnh. Bắt đầu một 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 đối số không bắt buộc.
@cparam @cparam joiner discerner @ca{discerner}
Chi tiết về thông số.		 Tham số lệnh.
@par @par
Nội dung mô tả CLI không bắt buộc.		 Đoạn cụ thể trong CLI.
@csa @csa{prefix add} Lệnh Xem thêm. Đường 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ệp tham chiếu API.
@tổng quan @tổng quan Tạo đường liên kết đến trang OpenThread CLI Overview (Tổng quan về OpenThread CLI).
@netdata @netdata Tạo một đường liên kết đến Hiển thị và quản lý dữ liệu mạng bằng OT CLI.
@dataset @dataset Tạo một đường liên kết để Hiển thị và quản lý tập dữ liệu bằng OT CLI.
@udp @udp Tạo đường liên kết đến bài viết Kiểm thử chức năng UDP có giao thức 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

Bạn phải bật một số ghi chú về mã, chẳng hạn như tham số CLI hoặc dữ liệu đầu ra của lệnh một dòng duy nhất để 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ột, điều này có thể phá vỡ chế độ kết xuất đầu ra cho 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 thẻ nhận xét HTML, như được thể hiện trong hai ví dụ dưới đây.

Ví dụ đầu tiên là lệnh dns resolve. Có thể mất đến 6 tham số. Để hiển thị chính xác cú pháp bằng Doxygen trong khi vẫn truyền 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 bước kiểm tra make pretty, mỗi dòng trong số năm 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