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

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

हम openthread 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 पर की जाने वाली टिप्पणियों का एक पूरा उदाहरण यहां दिया गया है:

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

एचटीएमएल आउटपुट की समीक्षा करने के लिए, 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 का इस्तेमाल करें. एपीआई कॉपी करते समय यह पक्का करें कि ब्यौरा, एपीआई और सीएलआई कमांड, दोनों के लिए काम करे. ऐसे वाक्यांशों का इस्तेमाल करने से बचें जो सिर्फ़ फ़ंक्शन पर लागू होते हों, जैसे कि 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}.

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

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.

एचटीएमएल आउटपुट की समीक्षा करने के लिए, 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

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

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

* @csa{netdata publish dnssrp anycast}

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

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

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

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

उपनाम उदाहरण ब्यौरा
@cli @cli ba पोर्ट कमांड का नाम. सीएलआई टिप्पणी ब्लॉक शुरू करता है.
@कोड @code
ba पोर्ट
41953
हो गया
@endcode		 कमांड का उदाहरण.
@ca [@ca{prefix}] कमांड तर्क. वैकल्पिक आर्ग्युमेंट के लिए, ब्रैकेट [ ] का इस्तेमाल करें.
@cparam @cparam जॉइनर गणना @ca{discerner}
पैरामीटर की जानकारी.		 Command पैरामीटर.
@par @par
वैकल्पिक सीएलआई जानकारी.		 सीएलआई से जुड़े पैराग्राफ़.
@csa @csa{prefix add} निर्देश भी देखें. किसी दूसरे निर्देश से जुड़ा हुआ है.
@sa @sa otBorderRouterConfig यह भी देखें. एपीआई रेफ़रंस का लिंक बनाता है.
@खास जानकारी @खास जानकारी OpenThread सीएलआई की खास जानकारी के लिए लिंक बनाता है.
@netdata @netdata ओटी सीएलआई की मदद से डिसप्ले और नेटवर्क डेटा मैनेज करें का लिंक बनाता है.
@dataset @dataset ओटी सीएलआई की मदद से डेटासेट दिखाएं और मैनेज करें का लिंक बनाता है.
@udp @udp ओटी सीएलआई की मदद से यूडीपी फ़ंक्शन की जांच करने के लिए लिंक बनाता है.
@moreinfo @moreinfo{@netdata} रेफ़रल लिंक बनाता है.
@note @note के लिए ज़रूरी कॉलआउट. इससे नोट कॉलआउट बॉक्स बनता है.

make pretty स्क्रिप्ट की गड़बड़ी वाली लाइनों को ठीक करना

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

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

पहला उदाहरण dns resolve कमांड है, जिसमें छह पैरामीटर तक लग सकते हैं. make pretty जांच पास करते समय, Doxygen का इस्तेमाल करके सिंटैक्स को सही तरीके से रेंडर करने के लिए, पैरामीटर को सोर्स में तीन लाइनों में बटाना होगा:

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