دستورات 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. قبل از شروع منطق، بلوک @cli Doxygen را شروع کنید:

   /**
    * @cli ba state
   

4. سپس، بلافاصله زیر @cli ، نمونه‌هایی را با استفاده از @code اضافه کنید. حداقل یک مثال را وارد کنید. درخواست > را وارد نکنید و مطمئن شوید که خروجی بازگشتی کامل، از جمله پاسخ استاندارد 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 توسط یک بلوک نظر پیوسته گروه‌بندی می‌شوند که با تگ 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 public prefix :

 * @cli netdata publish prefix

سایر دستورات ممکن است پیچیده تر باشند. به عنوان مثال، netdata publish dnssrp unicast چند گزینه را ارائه می دهد:

1. انتشار با آدرس و شماره پورت
2. انتشار بر اساس شماره پورت و EID مش-محلی دستگاه

اگر دستوری بیش از حد بارگذاری شده است، از پرانتز برای شناسایی منحصر به فرد دستور استفاده کنید.

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

توضیحات فرمان

سه راه برای مستندسازی توضیحات دستورات وجود دارد. می توانید توضیحات 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 باید یک نظر پیوسته و بدون فاصله باشند. اگر فهرستی را زیر @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ها

می‌توانید با #otFunctionName یا @sa به روش‌ها یا توابع API دیگر پیوند دهید. این پیوندها را در انتهای بلوک نظرات 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 . برای جلوگیری از پیوند داکسیژن به کلمات کلیدی یا نام کلاس های استفاده شده در یک جمله، از عملگر % در جلوی کلمه استفاده کنید، به عنوان مثال:

Clear the %Joiner discerner

برای اطلاعات بیشتر، به تولید لینک خودکار در راهنمای Doxygen مراجعه کنید.

پیوند خودکار به دستورات دیگر

@csa برای پیوند دادن به دستورات دیگر استفاده کنید.

* @csa{netdata publish dnssrp anycast}

اگر دستوری بیش از حد بارگذاری شده است، پرانتزها را وارد کنید و در صورت وجود یک کاما اضافه کنید. از فاصله داخل پرانتز استفاده نکنید:

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

دستورات ویژه داکسیژن

دستورات CLI از نام مستعار Doxygen و دستورات ویژه زیر پشتیبانی می کنند:

رفع خطوط شکسته شده توسط اسکریپت make pretty

برخی از نظرات کد، مانند پارامترهای CLI یا خروجی فرمان، باید در یک خط باشند تا بتوانند به درستی در مرجع openthread.io ارائه شوند. با این حال، make pretty یک محدودیت عرض ستون را تحمیل می کند، که می تواند خروجی رندر شده را برای خطوط طولانی بشکند.

همانطور که در دو مثال زیر نشان داده شده است، می توان با اضافه کردن خطوط شکسته و محصور کردن آنها با یک تگ نظر HTML، این وضعیت را برطرف کرد.

اولین مثال دستور dns resolve است که می تواند تا شش پارامتر را به خود اختصاص دهد. برای رندر صحیح نحو با استفاده از Doxygen در حالی که هنوز چک make pretty را انجام می دهید، پارامترها باید در سه خط در منبع تقسیم شوند:

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

مثال دوم خروجی دستور history ipaddr list 5 است. برای اینکه خروجی به درستی رندر شود و همچنان از بررسی make pretty عبور کند، هر یک از پنج خط خروجی باید به دو خط تقسیم شوند، به شرح زیر:

* 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