الأكسجين

دوكسجين ( يُلفظ / ˈdɒksidʒən / دوك - سي -جين ) [ ^{3 ]} هو مولد وثائق ^{[ 4 ] [ 5 ] [ 6 ] [ 7} ] يعمل مع العديد من ^لغات البرمجة . يستخرج المعلومات من تعليقات شفرة المصدر المنسقة خصيصًا ويحفظها ^في أحد التنسيقات المتعددة المدعومة .

يدعم Doxygen التحليل الثابت لقاعدة التعليمات البرمجية . ويستخدم شجرة التحليل المُستخرجة من قاعدة التعليمات البرمجية لإنشاء مخططات ورسوم بيانية لبنية التعليمات البرمجية. كما يوفر خاصية الربط المرجعي التي تُمكّن القارئ من الرجوع إلى التعليمات البرمجية المصدرية من الوثائق المُنشأة.

يمكن استخدام Doxygen في العديد من سياقات البرمجة. وهو يدعم لغات برمجة متعددة، منها ^{C ، و} C ++ ^، و ^C # ^، و ^D ، ^و Fortran ، ^و IDL ، ^{وJava، وObjective-C، وPerl، و} PHP ، ^و Python ، ^و VHDL ^. ويمكن ^تشغيله على أنظمة ^تشغيل متنوعة ، ^بما في ذلك أنظمة Unix و macOS ^و Windows ^. وهو برنامج ^مجاني ، مُرخص بموجب ^رخصة جنو العمومية العامة الإصدار الثاني ( ^GPLv2 ). 

استعار الإصدار الأول من Doxygen شفرة برمجية من إصدار مبكر من DOC++، الذي طوره رولاند وندرلينغ ومالتي زوكلر في معهد زوس ببرلين . وفي وقت لاحق، أعاد ديمتري فان هيش كتابة شفرة Doxygen.

يُستضاف كود مصدر Doxygen على GitHub ، حيث يُساهم المطور الرئيسي، ديمتري فان هيش، تحت اسم "doxygen". ^{[ 14 ]} كُتب Doxygen بلغة C++، ويتألف من حوالي 300,000 سطر من التعليمات البرمجية . لتحليل المعجم ، يُستخدم Lex (أو بديله Flex) عبر حوالي 35,000 سطر من نص برمجي lex. كما تُستخدم أداة التحليل Yacc (أو بديلها Bison )، ولكن فقط للمهام البسيطة. يتم تنفيذ الجزء الأكبر من التحليل باستخدام كود C++ أصلي. يتضمن نظام البناء CMake ونص برمجي Python .

على غرار مولدات التوثيق الأخرى مثل Javadoc ، يستخلص Doxygen المعلومات من كلٍّ من التعليقات والرموز البرمجية (غير التعليقات). يرتبط التعليق برمز برمجي بوضعه مباشرةً قبله في الكود. تتيح علامات التنسيق في التعليقات التحكم في تضمين وتنسيق التوثيق الناتج.

يدعم Doxygen الإخراج في العديد من التنسيقات بما في ذلك: HTML و CHM و RTF و PDF و LaTeX و PostScript و man page .

يستطيع برنامج Doxygen إنشاء مخططات التوريث لفئات لغة C++ . وللحصول على مخططات ورسوم بيانية أكثر تقدماً، يمكن لبرنامج Doxygen استخدام أداة "dot" من برنامج Graphviz . ^{[ 15 ]}

جميع الأمثلة معطاة للغات التي تحتوي على تعليقات تشبه لغة C حيث يبدأ التعليق متعدد الأسطر بـ /*ويبدأ التعليق ذو السطر الواحد بـ //.

يتجاهل Doxygen التعليقات ما لم يتم تمييزها بشكل خاص. بالنسبة للتعليقات متعددة الأسطر، يجب أن يبدأ التعليق بـ ` <div>` /**أو ` /*!<div>`. تُسبق علامة التنسيق بشرطة مائلة عكسية (` \\`) أو علامة @ (`@ @`). ^{[ 16 ]} فيما يلي مثال بسيط لتعليق دالة مع التنسيق بالخط العريض:

/* * * وصف الدالة * @param p1 وصف المعامل * @param p2 وصف المعامل * @return وصف القيمة المرجعة */ void foo(int p1, int p2) {}

يمكن تنسيق الكتلة بطرق مختلفة. إحدى الطرق الشائعة هي محاذاة علامات النجمة إلى اليسار في كل سطر، وهي طريقة لا يُدرجها برنامج Doxygen في المخرجات. على سبيل المثال:

/* * * وصف الدالة * @param p1 وصف المعامل * @param p2 وصف المعامل * @return وصف القيمة المرجعة */ void foo(int p1, int p2) {}

بدلاً من ذلك، يمكن أن تتكون الكتلة من سلسلة من التعليقات المكونة من سطر واحد. يقبل Doxygen التعليقات التي تحتوي على شرطة مائلة إضافية ( /) أو علامة تعجب ( !). ^{[ 17 ]}

// وصف الدالة // / @param p1 وصف المعامل // / @param p2 وصف المعامل // / @return وصف القيمة المرجعة void foo(int p1, int p2) {}

لتحديد موقع تعليق توثيقي على يمين الكود، <يلزم وجود علامة إضافية. ^{[ 18 ]} يتيح ذلك اتباع نهج بديل لتوثيق المعلمات كما هو موضح أدناه.

/* * * وصف الوظيفة */ void foo(int p1 /**<وصف المعامل*/, int p2 /**<وصف المعامل*/) {}

يمكن تحديد الصيغة الرياضية باستخدام أوامر LaTeX . على سبيل المثال:

/** * معادلة مضمنة @f$ e^{\pi i}+1 = 0 @f$ * معادلة معروضة: @f[ e^{\pi i}+1 = 0 @f] */

مثال أكثر اكتمالاً بلغة C++:

/** * @file Time.cpp * @module org.wikipedia.util.Time * @brief Time class * @author John Doe <jdoe@example.com> * @version 1.0 * @copyright CC BY-SA أو GFDL * @sa <a href="https://en.wikipedia.org/wiki/Wikipedia:Copyrights">Wikipedia:Copyrights - ويكيبيديا</a> */تصدير الوحدة النمطية org.wikipedia.util.Time ؛​​​​​استيراد org.wikipedia.core ؛ استيراد org.wikipedia.util.Date ؛​​​​​​​​​​باستخدام org :: wikipedia :: core :: ISerializable ;/** * @namespace org::wikipedia::util * @brief مساحة اسم لفئات الأدوات المساعدة */ export namespace org :: wikipedia :: util {/** * @class Time * @brief يمثل لحظة زمنية * @author John Doe * * يمثل الصنف Time مقدار الوقت المنقضي * منذ حقبة يونكس. * * @extends Date * @implements ISerializable */ class Time : public Date , public ISerializable { private : int64_t millis ; ///< عدد المللي ثواني منذ 1 يناير 1970 public : /**  * إنشاء كائن Time جديد بمدة زمنية منذ 1 يناير 1970  * @param millis عدد المللي ثواني  */ explicit Time ( int64_t millis ) : millis { millis } {}/**  * الحصول على نسخة جديدة بالوقت الحالي  * @return Instance  */ [[ nodiscard ]] static Time now () { // ... }/**  * الحصول على عدد المللي ثواني المُمثلة بكائن الوقت  * @return العدد الصحيح int64_t الذي يُمثل عدد المللي ثواني  */ [[ nodiscard ]] int64_t getTime () const noexcept { return millis ; } };}

• مقارنة بين مولدات الوثائق
• جافادوك
• كاتب واجهة برمجة التطبيقات

• الموقع الرسمي