تعديل أوامر OT 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. التضمين في مثالاً واحدًا على الأقل. لا تضمِّن الطلب >، وتأكَّد من توثيق النتائج الكاملة المردودة، بما في ذلك ردّ Done العادي

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

نظرًا لأنّ أوامر واجهة برمجة التطبيقات (CLI) توفّر إمكانية الوصول باستخدام سطر الأوامر إلى طرق واجهة برمجة التطبيقات الشائعة والدوال، تشترك بعض الأوامر في نفس الوصف واجهة برمجة التطبيقات المقابلة. إذا كان وصف الأمر هو نفسه، فأكمل الخطوات التالية:

1. يمكنك العثور على واجهة برمجة التطبيقات المرتبطة في openthread/include/openthread. الدليل. على سبيل المثال، يتم ربط ba state بـ otBorderAgentGetState.

2. استخدِم الأمر api_copy، ثم أدخِل اسم واجهة برمجة التطبيقات أسفلها مباشرةً. أمام تعريف واجهة برمجة التطبيقات، احرص على استخدام علامة الجنيه #. لإنشاء رابط Doxygen التلقائي.

   @par api_copy
   #otBorderAgentGetState
   

في ما يلي مثال كامل على الحدّ الأدنى من تعليقات Doxygen المطلوبة إنشاء أمر OT CLI تلقائيًا:

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

لمراجعة ناتج HTML، يُرجى الرجوع إلى ولاية ba. للاطّلاع على أمثلة متقدّمة وخيارات إضافية، يمكنك الرجوع إلى الأقسام التالية.

خيارات نموذج CLI

يتم تجميع أوامر واجهة سطر الأوامر حسب كتلة تعليقات واحدة مستمرة، بدءًا من علامة ALIAS @cli. تتوفّر عدة أمثلة من @code.

الترتيب الذي تحدّده كل علامة مهم.

• يجب أن يأتي @cparam بعد @code
• في حال نسخ وصف لواجهة برمجة التطبيقات، يجب أن يأتي @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":

1. النشر حسب العنوان ورقم المنفذ
2. النشر حسب رقم المنفذ ورقم معرّف شريحة SIM المضمّنة (EID) الخاص بالجهاز

إذا تم تحميل الأمر بشكل زائد، استخدِم الأقواس لتحديد الأمر بشكل فريد.

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

أوصاف الأوامر

هناك ثلاث طرق لتوثيق أوصاف الأوامر. يمكنك نسخ وصف واجهة برمجة التطبيقات، واستخدام وصف واجهة برمجة التطبيقات ولكن مع إضافة معلومات أخرى، أو تقدم وصفًا فريدًا تمامًا ينتمي إلى CLI. في الأقسام التالية، سنستعرض كل طريقة.

نسخ وصف واجهة برمجة التطبيقات المقابل

استخدِم api_copy لنسخ طريقة أو دالة واجهة برمجة التطبيقات المقابلة. فعندما في نسخ واجهات برمجة التطبيقات، فتأكد من أن الوصف سيعمل لكل من واجهة برمجة التطبيقات وأمر CLI. تجنب استخدام العبارات التي تنطبق فقط على ، على سبيل المثال This function أو This method. تفضيل صوت مستخدم نشط، مثلاً Gets the أو Sets the

 * @par api_copy
 * #otBorderAgentGetState

إضافة مزيد من المعلومات إلى وصف واجهة برمجة التطبيقات

إذا كنت تريد استخدام 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.

تظهر هذه الفقرات بعد وصف واجهة برمجة التطبيقات.

تقديم أوصاف خاصة بـ CLI فقط

تستخدم بعض أوامر CLI واجهات برمجة تطبيقات متعددة، أو تختلف عن طلب بيانات من واجهة برمجة التطبيقات. وهناك أنواع أخرى من البيانات لا تتضمن واجهة برمجة تطبيقات مرتبطة بها، مثل 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.

• ضع الأقواس [ ] حول الوسيطات الاختيارية.
• استخدِم الأشرطة العمودية | (الشُرط الرأسية) بين خيارات الوسيطات.
• لعرض تفاصيل المَعلمات، يمكنك إدخال جمل وقوائم Markdown. أسفل العلامة @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.

المَعلمات التي تتضمّن قوائم Markdown

ويمكنك أيضًا استخدام القوائم بعد @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 القوائم:

ربط واجهات برمجة التطبيقات تلقائيًا

يمكنك الربط بطرق أو دوال أخرى في واجهة برمجة التطبيقات باستخدام #otFunctionName أو @sa أدخل هذه الروابط في نهاية جزء تعليقات واجهة سطر الأوامر.

/**
 * @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 في العنوان مراجع واجهة برمجة التطبيقات وواجهة سطر الأوامر. لمراجعة HTML المخرجات، راجع بادئة netdata للنشر.

منع الروابط التلقائية

في بعض الأحيان، قد يخلط Doxygen بين كلمة عادية باعتبارها رابطًا لفئة واجهة سطر الأوامر، مثال، الكلمة 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 الخاصة

تتوافق أوامر واجهة سطر الأوامر مع أوامر Doxygen ALIASES والأوامر الخاصة التالية:

إصلاح الأسطر التي معطّلة بواسطة النص البرمجي "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