אינטרנט ישראל
  • ראשי
  • אודות רן בר-זיק ואינטרנט ישראל
  • ערוץ טלגרם
  • מסטודון
  • התחברו אלי בטוויטר
  • התחברו אלי בלינקדאין
  • ספר ג'אווהסקריפט
  • ראשי
  • אודות רן בר-זיק ואינטרנט ישראל
  • ערוץ טלגרם
  • מסטודון
  • התחברו אלי בטוויטר
  • התחברו אלי בלינקדאין
  • ספר ג'אווהסקריפט
ראשי » פיתוח אינטרנט » פתרונות ומאמרים על פיתוח אינטרנט » Doxygen

Doxygen

רן בר-זיק אפריל 17, 2011 7:42 am אין תגובות

מדריך מהיר לכתיבת הערות ותיעוד עם Doxygen במגוון שפות. כולל הסבר על התקנה ושימוש ב-Doxygen.

כדאי תמיד להשאר מעודכנים! אם יש לכם טלגרם, בדקו את ערוץ הטלגרם של האתר שבו אני מעדכן על פוסטים חדשים 🙂 אם אתם רוצים ללמוד תכנות באופן מקיף ומסודר, הצטרפו לאלפי הלומדים בפרויקט "ללמוד ג'אווהסקריפט בעברית" שמלמד לתכנת בג'אווהסקריפט, ב-Node.js ובריאקט וגם מלמד על תרומה לקוד פתוח. גם ספרים דיגיטליים וגם ספרים מודפסים. בשיתוף הקריה האקדמית אונו ובתמיכת חברות מובילות כגון Wix, Outbrain, Elementor, Iron Source, Chegg, Really Good ועוד.

קוד טוב הוא קוד מתועד ומוער היטב. כאשר אני כותב 'מוער' אני מתכוון להערות. הערות חשובות במיוחד הן עבור המתכנת עצמו והן עבור מתכנתים אחרים.
עבור מתכנתים אחרים התועלת ברורה, אך התועלת עצומה גם כלפי המתכנת עצמו. ראשית, הערות טובות מסייעות גם למי שכתב אותן אם הוא נדרש לגעת בקוד אחרי תקופה ארוכה. שנית, הערות שכתובות בפורמט מתאים יכולות לסייע מאד בשלב התיעוד אם משתמשים בתוכנת Doxygen. קוד עם הערות ברורות וסדורות ובנוסף לו גם דוקומנטציה מסודרת מוסיפים המון ערך לקוד. מתכנתים שכותבים הערות ותיעוד נחשבים למתכנתים מעולים, לפיכך כדאי לסגל את הרגל התיעוד עד שיהפוך לטבע שני לתכנות.

כתיבת ההערות בפורמט מסוים מאפשרות לנו להשתמש בתוכנת Doxygen כדי לייצר מסמכי תיעוד אוטומטיים מהקוד עצמו. איך המסמכים האלו נראים? שימו לב למסמכי התיעוד של מדיה-ויקי – תוכנה שכתובה ב-PHP.

ניתן להשתמש ב-Doxygen בכל שפה, ההדגמה שאני אדגים כאן היא ב-PHP, אך כמובן שניתן להשתמש בה ב-Java, C++, Python וכו'.

התקנת Doxygen על לינוקס

אם יש לכם שרת פיתוח מבוסס לינוקס (ולמה שלא יהיה לכם? שימו לב כמה קל להתקין!), קל מאד להתקין Doxygen:


sudo apt-get install doxygen

אגב, קל גם להתקין Doxygen על חלונות, הורידו את קובץ ה-doxygen בדף ההורדות ועקבו אחר ההוראות.

שימוש ב-Doxygen על גבי לינוקס

ראשית בואו וניצור 'פרויקט', ניצור קובץ PHP בשם כלשהו (כמו test.php) שיכיל את התוכן הבא:


<?php
/**
* @file
* Test file intended for doxygen testing
* @see https://internet-israel.com
*/


/**
 * does nothing
 *
 * @param teste
 * @return null
 */

function foo($foo) {
    echo 'hi'.$foo;
    return null;
}


מדובר בקובץ פשוט ביותר שמכיל הערות לפי תקן Doxygen, אני אסביר יותר מאוחר מה הן. כרגע תקבלו את זה As-Is.

יצירת קובץ הגדרות

אחרי שיצרנו את 'הפרויקט', עלינו ליצור קובץ הגדרות. כיצד יוצרים קובץ שכזה? מאד פשוט, באותה תיקיה שבה נמצא הקובץ אנו נכתוב:


doxygen -g

אנו יכולים לפרט את שם הקובץ, אבל כרגע לא. מיד נוצר קובץ בשם Doxyfile שמכיל את כל ההגדרות שלנו. אפשר לפתוח את הקובץ ולהסתכל על הגדרות. יש מיליון הגדרות ולכל אחת מהן יש הסבר. כך למשל אנו יכולים לפרט את שם הפרויקט והסברים נוספים, לציין אם אנו רוצים רקורסיה (צלילה אל תוך תיקיות בפרויקט) ועוד שאר פיצ'רים מעניינים. אנו בשלב זה לא ניגע בקובץ ההגדרות.

בניית הדוקומנטציה

בניית הדוקומנטציה היא קלה מאד, פשוט לכתוב:


doxygen Doxyfile

ריצה קצרה ותגלו שנוצרו אצלכם שתי תיקיות – html ו-latex, אם תכנסו עם הדפדפן לתיקית html תגלו את הדוקומנטציה! הנה דוגמא לדוקומנטציה שאתם אמורים לקבל.

זה הכל! מאד קל לייצר דוקומנטציה מלאה בהתבסס על ההערות שלכם.

הסבר על פורמט ההערות

ישנם כמה כללים ברורים בנוגע למבנה ההערות שיש לכתוב על מנת שיתאימו למסמך Doxygen, אני אפרט חלק מהם:

שם קובץ

על כל קובץ להכיל את הטקסט הבא על מנת שייקלט לתוך Doxygen:


/**
 * @file
 * File short name (80 charactars)
 *
 * Short description
 */

פונקציות

על כל פונקציה להכיל לפחות מינימום של תיאור קצר כאשר נדרש תיעוד של הפרמטרים ושל מה שהיא מחזירה אם יש פרמטרים והיא מחזירה משהו:


/**
 * short description
 *
 * long description
 *
 * @param object $varname
 *   Description
 *
 * @param array $arrname
 *   Description
 *
 * @return varname
 *   Description
 *
 * @see OtherObject::somemethod()
 *
 * @ingroup somegroup
 */

ניתן לכתוב [email protected] עם שמות של פונקציות, מתודות או אובייקטים (ניתן לכלול כמה כאלו) וגם לציין קבוצות שונות.

משתנים וקבועים

מגדירים משתנים וקבועים באופן הבא:


/**
 * description
 */
define('MY_CONSTANT', 0);

/**
 * description
 *
 * @see some_function()
 */
global $var;

בתחילה קשה להתרגל ולכתוב את כל המגילות האלו ליד כל פונקציה, אך בטווח הארוך מדובר באחת הטובות הכי גדולות שתעשו לעצמכם בדרך להיות מתכנתים יותר טובים.

כדאי תמיד להשאר מעודכנים! אם יש לכם טלגרם, בדקו את ערוץ הטלגרם של האתר שבו אני מעדכן על פוסטים חדשים 🙂 אם אתם רוצים ללמוד תכנות באופן מקיף ומסודר, הצטרפו לאלפי הלומדים בפרויקט "ללמוד ג'אווהסקריפט בעברית" שמלמד לתכנת בג'אווהסקריפט, ב-Node.js ובריאקט וגם מלמד על תרומה לקוד פתוח. גם ספרים דיגיטליים וגם ספרים מודפסים. בשיתוף הקריה האקדמית אונו ובתמיכת חברות מובילות כגון Wix, Outbrain, Elementor, Iron Source, Chegg, Really Good ועוד.
מידע למפתחים

השארת תגובה

ביטול

ללמוד ג'אווהסקריפט בעברית

ללמוד לתכנת ג'אווהסקריפט בעברית שגייס יותר משלוש מאות אלף שקל ולמעלה מ-2000 תומכים - בואו ללמוד עכשיו איך לתכנת.

רשימת הנושאים
  • מדריכים
    • ריאקט
    • טייפסקריפט
    • ECMAScript 6
    • ES20XX
    • Node.js
    • Express
    • רספברי פיי
    • Babel
    • docker
    • MongoDB
    • Git
    • לימוד MySQL
    • SASS
    • jQuery
    • CSS3
    • HTML 5
    • SVN
    • LESS
  • פיתוח אינטרנט
    • פתרונות ומאמרים על פיתוח אינטרנט
    • jQuery Scripts
    • jQuery למתקדמים
    • יסודות בתכנות
    • נגישות אינטרנט
  • חדשות אינטרנט
  • מידע כללי על אינטרנט
    • רשת האינטרנט
    • בניית אתרי אינטרנט
  • rss logo

    לכל המאמרים

    לכל המאמרים שפורסמו באינטרנט ישראל משנת 2008 ועד עכשיו.
  • rss logo

    RSS Feed

    משתמשים בקורא RSS? אם כן, עקבו אחרי אינטרנט ישראל באמצעות פיד ה-RSS!
    מה זה RSS?
  • Twitter logo

    עקבו אחרי בטוויטר

    בחשבון הטוויטר שלי אני מפרסם עדכונים מהירים על חדשות בתחום התכנות והיזמות, התרעות על מצבי חירום ורכילות בוערת על תחום הווב.
    מה זה טוויטר?
  • facebook like image

    ערוץ הטלגרם של אינטרנט ישראל

    בערוץ הטלגרם של אינטרנט ישראל אני מפרסם את הפוסטים של באתר וכן עדכונים טכנולוגיים נוספים.
    מה זה טלגרם?
  • github logo

    הפרויקטים שלי בגיטהאב

    הפרויקטים שאני כותב ושוחררו לציבור ברישיון קוד פתוח נמצאים ברובם בגיטהאב.
חיפוש

כל הזכויות שמורות לרן בר-זיק ולאינטרנט ישראל | מדיניות הפרטיות של אתר אינטרנט ישראל | אתר אינטרנט ישראל נגיש לפי תקן WCAG 2.0 AA | הצהרת הנגישות של האתר | אבטחת מידע ודיווח על בעיית אבטחת מידע

גלילה לראש העמוד