تعديل أوامر 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. بعد ذلك، أسفل @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 publish البادئة:

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

أوصاف الطلبات

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

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

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

الياس مثال الوصف
@cli منفذ @cli ba اسم الأمر. بدء قالب تعليقات CLI.
@code @code
baport
41953
تمّ
@endcode		 مثال على الأوامر.
@ca [@ca{prefix}] وسيطة الأمر استخدِم الأقواس [ ] للوسيطات الاختيارية.
@cparam @cparam joiner discerner @ca{discerner}
تفاصيل المَعلمة.		 مَعلمات الأوامر
@par @par
وصف CLI اختياري.		 فقرات محددة من واجهة سطر الأوامر.
@csa @csa{prefix add} اطّلِع أيضًا على الأوامر. يؤدي إلى أمر آخر.
@sa @sa otBorderRouterConfig راجع أيضًا. تنشئ رابطًا إلى مرجع واجهة برمجة التطبيقات.
@overview @overview تنشئ رابطًا إلى نظرة عامة على واجهة سطر الأوامر لـ OpenThread.
@netdata @netdata تُنشئ رابطًا يؤدي إلى عرض بيانات الشبكة وإدارتها باستخدام OT CLI.
@dataset @dataset تنشئ رابطًا يؤدي إلى عرض مجموعات البيانات وإدارتها باستخدام OT CLI.
@udp @udp ينشئ رابطًا من أجل اختبار وظيفة UDP باستخدام واجهة سطر الأوامر الإضافية.
@moreinfo @moreinfo{@netdata} ينشئ رابط إحالة.
@note @note وسيلة شرح مهمة. يتم إنشاء مربّع وسيلة شرح للملاحظة.

إصلاح الأسطر التي يعطّلها النص البرمجي لـ make pretty

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