עדכון פקודות 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 מספקות גישה לשורת הפקודה לשיטות 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 state. בקטעים הבאים תמצאו דוגמאות מתקדמות ואפשרויות נוספות.

אפשרויות של תבניות 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 הפקודה:

 * @cli netdata publish prefix

יכול להיות שפקודות אחרות יהיו מורכבות יותר. לדוגמה, ב-netdata publish dnssrp unicast יש כמה אפשרויות:

1. פרסום לפי כתובת ומספר יציאה
2. פרסום לפי מספר יציאה ו-Mesh-Local EID של המכשיר

אם הפקודה עמוסה מדי, מוסיפים סוגריים כדי לזהות אותה באופן ייחודי.

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

תיאורי הפקודות

יש שלוש דרכים לתעד תיאורים של פקודות. אפשר להעתיק את בתיאור ה-API, השתמשו בתיאור ה-API אבל הוסיפו מידע נוסף, או לספק תיאור ייחודי לחלוטין ששייך רק פקודת CLI. בקטעים הבאים נסביר על כל אחת מהשיטות.

מעתיקים את התיאור התואם של ה-API.

כדי להעתיק את ה-method או הפונקציה המתאימות של ה-API, משתמשים ב-api_copy. מתי מעתיקים ממשקי 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.

• צריך להוסיף סוגריים מרובעים [ ] סביב ארגומנטים אופציונליים.
• שימוש בקווים אנכיים | (קווים אנכיים) בין אפשרויות ארגומנטים.
• כדי להציג פרטי פרמטרים, אפשר להזין משפטים ורשימות 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 publish prefix

פרמטרים עם רשימות 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.

לדוגמאות נוספות, ראו רשימות.

קישור אוטומטי של ממשקי API

אפשר לקשר לשיטות או לפונקציות אחרות של API באמצעות #otFunctionName או @sa. הזינו את הקישורים האלה בסוף קטע התגובות ב-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 References. כדי לבדוק את קוד ה-HTML של הפלט, מתייחס netdata published prefix (קידומת לפרסום ב-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 הבאות ובפקודות מיוחדות:

תיקון שורות שנקטעו על ידי הסקריפט 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