OT CLI निर्देश अपडेट करें

GitHub पर सोर्स देखें

हम सीएलआई कमांड जनरेट करते हैं में सीएलआई सोर्स फ़ाइलों से ओपनथ्रेड GitHub रिपॉज़िटरी.

इस गाइड में, पसंद के मुताबिक बनाई गई Doxygen टिप्पणियों को इस्तेमाल करने के बारे में निर्देश दिए गए हैं जिनका इस्तेमाल हम कमांड सूची बनाने में करते हैं.

अपनी प्रोफ़ाइल बनाना शुरू करें

किसी सीएलआई कमांड को दस्तावेज़ के तौर पर सेव करने के लिए, नीचे दिए गए चरणों को पूरा करें. यह ज़रूरी है कि आप दिए गए क्रम में इन चरणों का पालन करते हैं.

1. openthread/src/cli में मौजूद Cmd को ढूंढें डायरेक्ट्री. उदाहरण के लिए, 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
   

क्योंकि सीएलआई कमांड से, एपीआई के सामान्य तरीकों को कमांड-लाइन ऐक्सेस दिया जाता है और फ़ंक्शन, कुछ कमांड का वर्णन उनके जैसा ही होता है संबंधित एपीआई. अगर कमांड का ब्यौरा एक जैसा है, तो इसके लिए, नीचे दिया गया तरीका अपनाएं:

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 स्थिति. बेहतर उदाहरणों और अतिरिक्त विकल्पों के लिए, नीचे दिए गए सेक्शन देखें.

सीएलआई टेंप्लेट के विकल्प

सीएलआई निर्देशों को, टिप्पणियों के एक ब्लॉक के हिसाब से ग्रुप में रखा जाता है. इसकी शुरुआत 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 के बाद का कोई भी टेक्स्ट, कमांड के नाम का हेडर बन जाता है. इस हेडर का इस्तेमाल इसमें किया जाता है डाइनैमिक लिंकिंग, उदाहरण के लिए नेटडेटा पब्लिश करने का प्रीफ़िक्स आदेश:

 * @cli netdata publish prefix

अन्य निर्देश ज़्यादा जटिल हो सकते हैं. उदाहरण के लिए, netdata publish dnssrp unicast से कुछ विकल्प मिलते हैं:

1. पते और पोर्ट नंबर से पब्लिश करें
2. पोर्ट नंबर और डिवाइस के मेश-लोकल ईआईडी की मदद से पब्लिश करें

अगर कोई निर्देश ज़रूरत से ज़्यादा लोड हो गया है, तो निर्देश की खास तौर पर पहचान करने के लिए ब्रैकेट का इस्तेमाल करें.

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

निर्देश की जानकारी

कमांड ब्यौरे को दस्तावेज़ में शामिल करने के तीन तरीके हैं. आप एपीआई की जानकारी, एपीआई की जानकारी का इस्तेमाल करें, लेकिन अतिरिक्त जानकारी जोड़ें, या एक ऐसा यूनीक ब्यौरा देते हैं जो सिर्फ़ सीएलआई निर्देश. अगले सेक्शन में, हम हर तरीके के बारे में जानेंगे.

एपीआई की जानकारी को कॉपी करें

एपीआई के उससे जुड़े तरीके या फ़ंक्शन को कॉपी करने के लिए, api_copy का इस्तेमाल करें. टास्क कब शुरू होगा आप API को कॉपी करते हैं, तो यह पक्का करें कि विवरण दोनों एपीआई और CLI निर्देश. ऐसे वाक्यांशों का इस्तेमाल करने से बचें जो सिर्फ़ फ़ंक्शन, उदाहरण के लिए This function या This method. प्राथमिकता दें ऐक्टिव वॉइस. जैसे, Gets the या Sets the.

 * @par api_copy
 * #otBorderAgentGetState

एपीआई की जानकारी में ज़्यादा जानकारी जोड़ें

अगर आपको api_copy का इस्तेमाल करना है, लेकिन अगर आपको इस बारे में और जानकारी जोड़नी हो सिर्फ़ सीएलआई निर्देश पर लागू होता है. इसके लिए, @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.

ये पैराग्राफ़, एपीआई की जानकारी के बाद दिखते हैं.

सिर्फ़ सीएलआई के हिसाब से जानकारी दें

कुछ सीएलआई कमांड, एक से ज़्यादा एपीआई का इस्तेमाल करते हैं या ये एपीआई कॉल से अलग होते हैं. अन्य के पास कोई एपीआई नहीं होता, जैसे कि 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}.

एचटीएमएल आउटपुट की समीक्षा करने के लिए, netdata published प्रीफ़िक्स देखें.

मार्कडाउन सूचियों वाले पैरामीटर

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

एचटीएमएल आउटपुट की समीक्षा करने के लिए, 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 लिंक दिखते हैं. एचटीएमएल की समीक्षा करने के लिए आउटपुट के लिए, इसे देखें netdata published प्रीफ़िक्स का इस्तेमाल करना.

ऑटोमैटिक लिंक इस्तेमाल करने से रोकना

कभी-कभी, Doxygen किसी सामान्य शब्द को सीएलआई क्लास का लिंक समझने की गलती कर सकता है, उदाहरण के लिए, शब्द Joiner. Doxygen को कीवर्ड या क्लास से लिंक करने से रोकने के लिए किसी वाक्य में इस्तेमाल किए गए नामों के लिए, शब्द से पहले % ऑपरेटर का इस्तेमाल करें, उदाहरण के लिए:

Clear the %Joiner discerner

ज़्यादा जानकारी के लिए, इसे देखें लिंक का अपने-आप जनरेट होना देखें.

अन्य निर्देशों से अपने-आप लिंक करें

दूसरे निर्देशों से लिंक करने के लिए @csa का इस्तेमाल करें.

* @csa{netdata publish dnssrp anycast}

अगर कोई निर्देश ज़रूरत से ज़्यादा लोड हो गया है, तो ब्रैकेट को शामिल करें और कॉमा लगाएं अगर लागू हो. ब्रैकेट के अंदर स्पेस का इस्तेमाल न करें:

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

Doxygen के लिए खास निर्देश

सीएलआई कमांड, इन Doxygen ALIASES और खास निर्देशों के साथ काम करते हैं:

make pretty स्क्रिप्ट के उल्लंघन से जुड़ी लाइनों को ठीक करना

कुछ कोड टिप्पणियां, जैसे सीएलआई पैरामीटर या कमांड आउटपुट एक लाइन होनी चाहिए, ताकि वे OpenThread.io रेफ़रंस में सही तरीके से रेंडर हो सकें. हालांकि, make pretty कॉलम की चौड़ाई की सीमा लागू करता है. इससे रेंडर की गई इमेज की क्वालिटी में गड़बड़ी आ सकती है लंबी लाइन का आउटपुट.

इस समस्या का समाधान लाइन ब्रेक जोड़कर और उन्हें बंद करके किया जा सकता है जिसमें एक एचटीएमएल टैग शामिल है, जैसा कि नीचे दो उदाहरणों में दिखाया गया है.

पहला उदाहरण 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