אנחנו יוצרים פקודות CLI מקובצי המקור של ה-CLI שבמאגר openthread ב-GitHub.
במדריך הזה מוסבר איך להשתמש בתגובות מותאמות אישית של Doxygen, שבהן אנחנו משתמשים כדי ליצור את רשימת הפקודות.
תחילת העבודה
כדי לתעד פקודה של CLI, צריך לבצע את השלבים הבאים. חשוב לבצע את השלבים הבאים לפי הסדר שלהם.
מאתרים את ה-
Cmd
המשויך בספרייהopenthread/src/cli
. לדוגמה: כדי למצוא אתba state
, מחפשים אתCmd("ba")
. לכל פקודה תהיה תבנית משויכת של פונקציה:template <> otError Interpreter::Process<Cmd("ba")>(Arg aArgs[])
בתבנית הפונקציה, מאתרים את לוגיקת הפקודות הנכונה. לדוגמה,
ba state
:else if (aArgs[0] == "state")
לפני שהלוגיקה מתחילה, צריך להפעיל את בלוק החמצן של
@cli
:/** * @cli ba state
לאחר מכן, מתחת ל-
@cli
, מוסיפים דוגמאות באמצעות@code
. הוסיפו לפחות דוגמה אחת. לא כדאי לכלול את ההודעה>
, ולהקפיד לתעד את הפלט המלא של ההחזרה, כולל התגובה הרגילה שלDone
.* @code * ba state * Started * Done * @endcode
מכיוון שפקודות CLI מספקות גישה דרך שורת הפקודה לשיטות ולפונקציות נפוצות של ה-API, לחלק מהפקודות יש תיאור זהה לזה של ה-API התואם. אם תיאור הפקודה זהה, מבצעים את השלבים הבאים:
מאתרים את ה-API המשויך בספרייה
openthread/include/openthread
. לדוגמה,ba state
ממופה אלotBorderAgentGetState
.משתמשים בפקודה
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
יש כמה אפשרויות:
- פרסום לפי כתובת ומספר יציאה
- פרסום לפי מספר יציאה ו-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