עדכון פקודות 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. לפני שהלוגיקה מתחילה, צריך להפעיל את בלוק החמצן של @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 publish באמת.

 * @cli netdata publish prefix

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

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

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

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

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

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

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

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

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

קישור אוטומטי של ממשקי 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.

מניעת קישורים אוטומטיים

לפעמים 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 port	שם הפקודה. הפעלת חסימת תגובות ב-CLI.
@code	@code ba port 41953 סיום @endcode	דוגמה לפקודה.
@ca	[@ca{prefix}]	ארגומנט של פקודה. אפשר להשתמש בסוגריים [ ] לארגומנטים אופציונליים.
@cparam	@cparam joinerdiserner @ca{discerner} פרטי הפרמטר.	פרמטרים של פקודות.
@par	@par תיאור אופציונלי של ה-CLI.	פסקאות ספציפיות ל-CLI.
@csa	@csa{prefix add}	הפקודה, 'פרטים נוספים'. קישור לפקודה אחרת.
@sa	@sa otBorderRouterConfig	ראו בנוסף. יוצר קישור להפניה ל-API.
@overview	@overview	קישור לסקירה הכללית של ה-CLI של OpenThread
@netdata	@netdata	יוצר קישור לרשת המדיה וניהול של נתוני הרשת באמצעות CLI של OT.
@dataset	@dataset	יוצר קישור להצגה וניהול של מערכי נתונים באמצעות CLI של OT.
@udp	@udp	יצירת קישור לבדיקת פונקציונליות UDP באמצעות OT CLI.
@moreinfo	@moreinfo{@netdata}	יוצר קישור מפנה.
@note	@note הסבר חשוב.	יצירת תיבת הסבר להערה.

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