Doxygen

דוקסיג'ן (באנגלית: Doxygen /ד ɒ k s i dʒ ən / DOK -see-jən) הוא מחולל תיעוד, כלי לכתיבת תיעוד הפניה לשורות קוד בתכנה. התיעוד נכתב על ידי המתכנת (המקודד) בתוך מקטעי שורות הקוד במהלך התכנות, דבר שמאפשר שמירה על עדכניות התיעוד לגבי שינויים/תוספות שנעשו בתוכניות. דוקסיג'ן יכול להצליב תיעוד וקוד (כלומר, התיעוד שיחולץ משורות הקוד יכלול הפניה מדויקת למקור ממנו חולץ), כך שקורא מסמך התיעוד יכול להבין בקלות לאילו שורות קוד בפועל מפנה התיעוד. הגרסה הראשונה של דוקסיג'ן 'השאילה' קוד מגרסה מוקדמת של ++DOC, חבילת תוכנה שפתחו רולנד וונדרלינג ומלטה זוקלר במכון Zuse Berlin. מאוחר יותר, שוכתב קוד דוקסיג'ן על ידי דימיטרי ואן היץ'. דוקסיג'ן הוא תוכנה חופשית, המופץ בתנאי הרישיון הציבורי הכללי של גנו GNU GPL, גרסה 2. דוקסיג'ן (כמו גם Javadoc) מחלץ תיעוד 'מהערות' מלל שנכתבו בקובץ שורות קוד המקור. הוא תומך בתחביר Javadoc וגם בתגיות תיעוד המשמשות בערכת הכלים Qt. דוקסיג'ן יכול להפיק פלט בשפת: HyperText Markup (HTML), Microsoft Compiled HTML Help, תבנית מלל עשיר (RTF), תבנית מסמך נייד (PDF), LaTeX, פוסטסקריפט או דפי man. דוקסיג'ן תומך במספר רב של שפות תכנות וביניהן: C, C ++, C #, D, Fortran, IDL, Java, Objective-C, Perl, PHP, Python ו- VHDL. מאחר שדוקסיג'ן הוא למעשה חבילת קוד פתוח, המשמעות היא שעל ידי הוספת קוד עצמאי, ניתן להרחיב את התמיכה, על פי הצורך, גם לשפות תכנות נוספות. דוקסיג'ן פועל ברוב מערכות ההפעלה: כול דמויי היוניקס לסוגיהם, MacOS ו-Windows. אחת מהתכונות המובנות בדוקסיג'ן היא היכולת להפיק תרשימי תלויות וירושה לשכבות שפת ++C, יכולת זו מאפשרת תצוגה חזותית של תלויות קוד ואובייקטי תכנה אלו באלו. על ידי שימוש בכלי 'dot' ו- Graphviz. ניתן אף להרחיב את היכולות החזותיות של דוקסיג'ן להפקת דיאגרמות ותרשימים מתקדמים ביותר. התחביר הגנרי להוספת הערות תיעוד לתוך שורות הקוד, נעשה על ידי הוספת כוכבית נוספת לאחר תו התיחום ולפני תחילת הזנת ההערה '/*': /** <A short one line description> <Longer description> <May span multiple lines or paragraphs as needed> @param Description of method's or function's input parameter @param ... @return Description of the return value */ לחלופין, ניתן גם לסמן התחלת שורה ברווח-כוכבית-רווח כדלקמן, אך אין זה הכרחי. /** * <A short one line description> * * <Longer description> * <May span multiple lines or paragraphs as needed> * * @param Description of method's or function's input parameter * @param ... * @return Description of the return value */ תוכניתנים רבים נמנעים מלעשות שימוש בהערות בסגנון C ובמקום זאת משתמשים בהערות בשורה יחידה בסגנון ++C. דוקסיג'ן מזהה ומקבל גם הערות עם לוכסן ימני נוסף, כמו בדומה הבאה: /// <A short one line description> /// /// <Longer description> /// <May span multiple lines or paragraphs as needed> /// /// @param Description of method's or function's input parameter /// @param ... /// @return Description of the return value הדוגמה הבאה מציגה את אופן תיעוד הערה בקובץ מקור בשפת ++C. /** * @file * @author John Doe <jdoe@example.com> * @version 1.0 * * @section LICENSE * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License as * published by the Free Software Foundation; either version 2 of * the License, or (at your option) any later version. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details at * https://www.gnu.org/copyleft/gpl.html * * @section DESCRIPTION * * The time class represents a moment of time. */ class Time { public: /** * Constructor that sets the time to a given value. * * @param timemillis is a number of milliseconds * passed since Jan 1, 1970. */ Time (int timemillis) { // the code } /** * Get the current time. * * @return A time object set to the current time. */ static Time now () { // the code } }; גישה חלופית לתיעוד משתנים בשורות הקוד מוצגת להלן. תוצאת מבנה התיעוד תהיה זהה בשני המקרים. /** * Constructor that sets the time to a given value. */ Time (int timemillis ///< Number of milliseconds passed since Jan 1, 1970.> ) { // the code } אפשר גם להשתמש בשפת סימון עשירה יותר. לדוגמה, הוספת משוואות באמצעות פקודות LaTeX : /** * * An inline equation @f$ e^{\pi i}+1 = 0 @f$ * * A displayed equation: @f[ e^{\pi i}+1 = 0 @f] * */ את קוד המקור של דוקסיג'ן נתן למצוא ב-GitHub, דימיטרי ואן היץ', המפתח הראשי של דוקסיג'ן, תומך בחבילה וממשיך לתורם בהתפתחותה תחת שם המשתמש 'דוקסיג'ן'. דוקסיג'ן כתוב בשפת ++C, וכולל למעלה מ-300,000 שורות קוד מקור. לניתוח מילולי, מופעל הכלי הסטנדרטי Lex (או מחליפו Flex) על יותר מ-35,000 שורות של תסריטי Lex. כלי ניתוח נוספים בהם נעשה שימוש: בכלי הניתוח Yacc (או מחליפו Bison), למשימות קלות קוד ++C, לניתוח שפה עיקרי CMake, לתהליך הבנייה כמה תסריטי פייתון. ניתוח תוכניות סטטי מדיה וקבצים בנושא Doxygen בוויקישיתוף אתר האינטרנט הרשמי של Doxygen (באנגלית) http://www.doxygen.nl/manual/changelog.html FAQ: How did doxygen get its name? Perkel, Jeffrey M. (2015-11-22). "Get With the Program: DIY tips for adding coding to your analysis arsenal". The Scientist (Journal). The Scientist. Sabin, Mihaela (2015-11-22). "Doxygen". OpenComputing (Wiki). University of New Hampshire. אורכב מ-המקור ב-2015-11-23. "Doxygen". Free Software Directory (Wiki). 2015-11-22. "Documentation". Rosetta Code (Wiki). 2015-11-22. "Documentation: C". Rosetta Code (Wiki). 2015-11-22. "Documentation: Objective-C". Rosetta Code (Wiki). 2015-11-22. http://search.cpan.org/perldoc?Doxygen%3A%3AFilter%3A%3APerl http://www.doxygen.nl/manual/starting.html "Automatic Python API documentation generation tools". python.org wiki (Wiki). 2015-11-22. https://pypi.python.org/pypi/doxypypy/ דוגמת תרשים תלות חזותי, Directed acyclic graph, Wikipedia, 2021-02-15 http://www.doxygen.nl/manual/diagrams.html https://github.com/doxygen/doxygen