בתיעוד שלמדנו במחברת צריך לכלול את ערך ההחזרה של הפונקציה, אבל אני לא מבינה איפה להכליל את הפעולות שהפונקציה עושה בלי קשר להחזרה.
למשל באורטל קומבט, פעולת revive. היא לא מחזירה דבר אבל עושה פעולה כלשהי. איך לתעד את זה?
מועתק ממחברת 2, מקווה שיוכל לעזור לך:
- Args: – רשימת הארגומנטים שהיא הולכת לקבל, סוגם והסבר קצר על כל אחד מהם.
- Returns: – הערך שהפונקציה מחזירה והסוג שלו. במקרה של generator החלק יקרא Yields : במקום.
- Raises: – השגיאות שהפונקציה עלולה לזרוק ובאילו מקרים זה עלול לקרות.
- Attributes: – התכונות של המופעים שייווצרו על ידי המחלקה.
בפונקציה או בפעולה – נסכם:
- מה מטרתה.
- אילו ארגומנטים היא מצפה לקבל.
- מהם ערכי ההחזרה שלה.
- אילו שגיאות היא עלולה להחזיר.
- על מה היא משפיעה חוץ מאשר על המשתנים בפונקציה עצמה (נניח – כתיבה לקובץ).
סימנתי ב- BOLD מה שרלוונטי אלייך
קראתי את המחברת XD זו בדיוק הנקודה.
בסיכום מופיע מה שאני שואלת עליו ( על מה היא משפיעה חוץ מאשר על המשתנים בפונקציה עצמה (נניח – כתיבה לקובץ).)
אבל אין לזה מקום מוגדר בתיאור התיעוד בפסקה הראשונה שהעתקת.
אני שואלת איפה למקם את זה, תחת איזו כותרת.
בשורה מתחת לפעולה את מתעדת את מטרתה בתמציתיות:
מפרידה עם שורת רווח ולאחר מכן כך:
Args:
usernames (list): Bla bla.
Attributes:
message_id (int): Bla bla.
boxes (dict): Bla bla.
Returns:
int: Bla bla.
Raises:
KeyError: Bla bla.
כאשר
Args - מקבל את הארגומנטים שלה במידה והוספת
Attributes - התכונות של המופעים שנוצרו במידה וישנם
Returns - מה מוחזר מהפעולה
Raises - השגיאות שעלולות לחזור במצבים מסויימים
וזו רק דוגמה יש עוד אפשרויות
2 לייקים
ואם פעולה לא מחזירה כלום? האם מדלגים על החלק הזה בתיעוד או שכותבים בו משהו על זה שהיא לא מחזירה כלום?
אם לדייק, אין פונקציה שלא מחזירה כלום, יש פונקציה שמחזירה None. אבל אני מניח שאפשר לדלג (:
בכל מקרה, @rogruman, מה שאת מציינת הם פרטי מימוש של הפעולה/פונקציה. לרוב למי שמשתמש בה זה צריך להיות שקוף. אם את בכל זאת חושבת שזה לא פרט מימוש אלא התנהגות שהמשתמש צריך להיות מודע אליה, תוסיפי על זה מלל בפסקה השנייה של התיעוד (זו שאחרי התיאור הקצר שאורכו שורה).
2 לייקים