PHPDocumentor هي أداة مكتوبة بلغة PHP بالنسبة لبرامج PHP ذات التعليقات التوضيحية القياسية، يمكنها إنشاء مستندات API بسرعة مع إسناد ترافقي وفهرسة ووظائف أخرى. النسخة القديمة هي phpdoc.
1. ما هو phpDocumentor؟
PHPDocumentor هي أداة مكتوبة بلغة PHP بالنسبة لبرامج PHP ذات التعليقات التوضيحية القياسية، يمكنها إنشاء مستندات API بسرعة مع إسناد ترافقي وفهرسة ووظائف أخرى. الإصدار القديم هو phpdoc، بدءًا من 1.3.0، تمت إعادة تسميته إلى phpDocumentor. يضيف الإصدار الجديد دعمًا لصيغة php5. وفي الوقت نفسه، يمكن إنشاء المستندات من خلال التشغيل على متصفح العميل، ويمكن تحويل المستندات إلى phpdoc PDF، HTML، هناك عدة أشكال من آلية تبادل المعلومات (CHM)، وهي مريحة للغاية.
عندما يعمل PHPDocumentor، فإنه سيقوم بمسح كود مصدر PHP ضمن الدليل المحدد، ومسح الكلمات الرئيسية، واعتراض التعليقات التي تحتاج إلى تحليل، ثم تحليل العلامات الخاصة في التعليقات، وإنشاء ملف xml، ثم بناءً على معلومات الفئات والوحدات النمطية التي تم تحليلها، وإنشاء الفهارس المقابلة، وإنشاء ملفات xml، واستخدام القوالب المخصصة لإخراج الملفات بالتنسيق المحدد لملفات xml التي تم إنشاؤها.
2. قم بتثبيت PHPDocumentor
مثل الوحدات الأخرى ضمن الكمثرى، ينقسم تثبيت phpDocumentor أيضًا إلى طريقتين: التثبيت التلقائي والتثبيت اليدوي، كلتا الطريقتين مريحتان للغاية:
أ. التثبيت تلقائيًا من خلال الكمثرى والدخول في سطر الأوامر
الكمثرى تثبيت PhpDocumentor
ب. قم بتثبيت أحدث إصدار من PhpDocumentor يدويًا (الآن 1.4.0) على http://manual.phpdoc.org/ وقم بفك ضغط المحتوى.
3. كيفية استخدام PhpDocumentor لإنشاء سطر أوامر التوثيق:
في الدليل الذي يوجد به phpDocumentor، أدخل
فب-ح
سوف تحصل على قائمة مفصلة بالمعلمات، والعديد من المعلمات المهمة منها كما يلي:
-f اسم الملف المراد تحليله، والملفات المتعددة مفصولة بفواصل
-d الدليل المراد تحليله، وأدلة متعددة مفصولة بفواصل
-t مسار تخزين المستند الذي تم إنشاؤه
-o تنسيق مستند الإخراج، والهيكل هو تنسيق الإخراج: اسم المحول: دليل القالب.
على سبيل المثال: phpdoc -o HTML:frames:earthli -f test.php -t docs
يتم إنشاء واجهة الويب في ملف phpdoc الجديد، بالإضافة إلى إنشاء مستندات على سطر الأوامر، يمكنك أيضًا إنشاء مستندات على متصفح العميل. والطريقة المحددة هي وضع محتوى PhpDocumentor أولاً في دليل Apache بحيث يمكن تخزينه يتم الوصول إليها من خلال المتصفح، وسيتم عرض الواجهة التالية بعد الوصول:
انقر فوق زر الملفات لتحديد ملفات أو مجلدات PHP المراد معالجتها. يمكنك أيضًا تجاهل معالجة ملفات معينة عن طريق تحديد الملفات التي سيتم تجاهلها في هذه الواجهة.
ثم انقر فوق زر الإخراج لتحديد مسار تخزين وتنسيق المستند الذي تم إنشاؤه.
أخيرًا، انقر فوق "إنشاء"، وسيبدأ phpdocumentor تلقائيًا في إنشاء المستندات، وسيتم عرض تقدم عملية الإنشاء وحالتها في الأسفل.
إجمالي وقت التوثيق: 1 ثانية
منتهي
اكتملت العملية!!
بعد ذلك، يمكننا عرض المستند الذي تم إنشاؤه إذا كان بتنسيق pdf، فسيكون الاسم الافتراضي هو document.pdf.
4. أضف التعليقات القياسية إلى كود php
يقوم PHPDocument بإنشاء مستندات من التعليقات الموجودة في الكود المصدري الخاص بك، وبالتالي فإن عملية التعليق على برنامجك هي أيضًا عملية تجميع الوثائق.
من وجهة النظر هذه، PHPdoc يشجعك على تطوير عادات برمجة جيدة ومحاولة استخدام المواصفات والنص الواضح للتعليق على برنامجك، وفي الوقت نفسه، يتجنب بشكل أو بآخر بعض مشاكل عدم التزامن بين إعداد المستند والمستند التحديثات بعد ذلك.
في phpdocumentor، تنقسم التعليقات إلى تعليقات توثيقية وتعليقات غير مستندية.
ما يسمى بالتعليقات التوثيقية عبارة عن تعليقات متعددة الأسطر موضوعة أمام كلمات رئيسية محددة تشير إلى الكلمات الرئيسية التي يمكن تحليلها بواسطة phpdoc، مثل class وvar وما إلى ذلك. لمزيد من التفاصيل، يرجى الاطلاع على الملحق 1.
التعليقات التي لا تسبق الكلمات الرئيسية أو غير موحدة تسمى التعليقات غير الموثقة، ولن يتم تحليل هذه التعليقات بواسطة phpdoc ولن تظهر في نص واجهة برمجة التطبيقات (API) الذي تقوم بإنشائه.
3.2 كيفية كتابة التعليقات التوثيقية:
جميع التعليقات التوثيقية عبارة عن تعليق متعدد الأسطر يبدأ بـ /**، والذي يسمى DocBlock في phpDocumentor. يشير DocBlock إلى معلومات المساعدة حول كلمة رئيسية معينة كتبها مطورو البرامج حتى يتمكن الآخرون من معرفة الغرض المحدد من الكلمات الرئيسية وكيفية استخدامها. يحدد PhpDocumentor أن DocBlock يحتوي على المعلومات التالية:
1. منطقة الوصف الموجز للوظيفة
2. منطقة الوصف التفصيلي
3. العلامة
السطر الأول من تعليق التوثيق هو منطقة وصف الوظيفة. يشرح النص بشكل عام وظيفة هذه الفئة أو الطريقة أو الوظيفة بشكل موجز، وسيتم عرض نص وصف الوظيفة في منطقة الفهرس في المستند الذي تم إنشاؤه. يمكن إنهاء محتوى منطقة وصف الوظيفة بسطر فارغ أو بعد منطقة وصف الوظيفة يكون هناك سطر فارغ، متبوعًا بمنطقة وصف تفصيلي، ويصف هذا الجزء بشكل أساسي وظيفة واجهة برمجة التطبيقات (API) والغرض منها بالتفصيل. يمكنك أيضًا أمثلة للاستخدام، وما إلى ذلك. في هذا القسم، يجب عليك التركيز على توضيح الغرض العام واستخدام وظائف أو أساليب واجهة برمجة التطبيقات (API)، والإشارة إلى ما إذا كانت مشتركة بين الأنظمة الأساسية (إذا كانت متضمنة). بالنسبة للمعلومات المتعلقة بالنظام الأساسي، يجب التعامل معها بشكل مختلف عن المعلومات العامة. الطريقة المعتادة هي بدء سطر جديد، ثم كتابة الاحتياطات أو المعلومات الخاصة على منصة معينة. يجب أن تكون هذه المعلومات كافية حتى يتمكن القراء من كتابة معلومات الاختبار المقابلة، مثل شروط الحدود، ونطاقات المعلمات، ونقاط التوقف، وما إلى ذلك.
بعد ذلك، يوجد أيضًا سطر فارغ، ثم علامة المستند، التي تشير إلى بعض المعلومات الفنية، وخاصة نوع معلمة الاتصال، وقيمة الإرجاع ونوعه، وعلاقة الميراث، والطرق/الوظائف ذات الصلة، وما إلى ذلك.
فيما يتعلق بوضع علامات على المستندات، يرجى الرجوع إلى القسم 4: وضع علامات على المستندات للحصول على التفاصيل.
يمكن أيضًا استخدام علامات مثل <b> <code> في تعليقات المستند، برجاء الرجوع إلى الملحق 2 للحصول على التفاصيل.
فيما يلي مثال على تعليق التوثيق
/**
* وظيفة الإضافة، تنفذ إضافة رقمين
*
* عملية حسابية بسيطة، تقبل الدالة رقمين a وb، وترجع مجموعهما c
*
* @param int إضافة
*param int summand
* @return عدد صحيح
*/
وظيفة إضافة($أ، $ب) {
إرجاع $a+$b;
}
الوثيقة التي تم إنشاؤها هي كما يلي:
يضيف
عدد صحيح إضافة (int $a، int $b)
[السطر 45]
وظيفة الإضافة، تنفذ عملية جمع رقمين
الثوابت هي عملية حسابية بسيطة تقبل الدالة رقمين a وb وترجع مجموعهما c.
حدود
• int $a - إضافة
• كثافة العمليات $ ب - الجمع
5. علامات الوثيقة:
يشير نطاق استخدام علامة المستند إلى الكلمات الأساسية أو علامات المستند الأخرى التي يمكن استخدام العلامة لتعديلها.
تبدأ جميع علامات التوثيق بـ @ بعد علامة * في كل سطر. إذا ظهرت العلامة @ في منتصف الفقرة، فسيتم التعامل مع العلامة على أنها محتوى عادي وسيتم تجاهلها.
@وصول
نطاق الاستخدام: الفئة، الوظيفة، فار، التعريف، الوحدة النمطية
تُستخدم هذه العلامة للإشارة إلى حقوق الوصول للكلمة الرئيسية: خاص أو عام أو محمي
@مؤلف
حدد المؤلف
@ حقوق الطبع والنشر
نطاق الاستخدام: الفئة، الوظيفة، فار، التعريف، الوحدة النمطية، الاستخدام
تحديد معلومات حقوق النشر
@مهمل
نطاق الاستخدام: الفئة، الوظيفة، فار، التعريف، الوحدة النمطية، المحتوى، العمومي، التضمين
الإشارة إلى الكلمات الرئيسية غير المستخدمة أو القديمة
@مثال
تُستخدم هذه العلامة لتحليل جزء من محتوى الملف وتسليط الضوء عليه. سيحاول Phpdoc قراءة محتوى الملف من مسار الملف الذي توفره هذه العلامة.
@const
نطاق الاستخدام: تحديد
يستخدم للإشارة إلى الثوابت المحددة في PHP
@أخير
نطاق الاستخدام: الفئة، الوظيفة، فار
يشير إلى أن الكلمة الأساسية هي فئة أو طريقة أو سمة نهائية، ويحظر اشتقاقها أو تعديلها.
@filesource
مشابه للمثال، إلا أن هذه العلامة ستقرأ مباشرة محتوى ملف php الذي تم تحليله حاليًا وستعرضه.
@عالمي
يشير إلى المتغيرات العامة المشار إليها في هذه الوظيفة
@ingore
يُستخدم لتجاهل الكلمات الأساسية المحددة في المستند
@رخصة
أي ما يعادل <a> في علامة html، أولاً هو عنوان URL، ثم المحتوى الذي سيتم عرضه، مثل <a href=”http://www.baidu.com”>Baidu</a>
يمكنك كتابةlicense http://www.baidu.com Baidu
@وصلة
على غرار الترخيص
ولكن يمكنك أيضًا الإشارة إلى أي كلمة رئيسية في المستند من خلال الرابط
@اسم
حدد اسمًا مستعارًا للكلمة الأساسية.
@طَرد
نطاق الاستخدام: مستوى الصفحة -> التحديد، الوظيفة، التضمين
مستوى الفصل->الفئة، فار، الأساليب
يُستخدم لتجميع كلمة رئيسية واحدة أو عدة كلمات رئيسية بشكل منطقي في مجموعة.
@abstrcut
يشير إلى أن الفئة الحالية هي فئة مجردة
@param
تحديد معلمات الوظيفة
@يعود
يحدد مؤشر الإرجاع للطريقة أو الوظيفة
@ثابت
يشير إلى أن الكلمة الأساسية ثابتة.
@فار
تحديد نوع المتغير
@إصدار
تحديد معلومات الإصدار
@todo
أشر إلى المجالات التي ينبغي تحسينها أو عدم تنفيذها
@رميات
يشير إلى استثناء الخطأ الذي قد تطرحه هذه الوظيفة في الحالات القصوى، كما هو مذكور أعلاه، يجب وضع علامة @ على علامات المستند العادية في بداية كل سطر، بالإضافة إلى ذلك، هناك أيضًا علامة تسمى العلامة المضمنة، باستخدام {@ } يعني ، بما في ذلك على وجه التحديد ما يلي:
{@وصلة }
الاستخدام هو نفس @link
{@مصدر }
عرض محتويات وظيفة أو طريقة
6. بعض مواصفات الشرح
أ. يجب أن يكون التعليق
/**
* ××××××
*/
استمارة
ب. بالنسبة للوظائف التي تشير إلى المتغيرات العامة، يجب استخدام العلامة glboal.
ج. بالنسبة للمتغيرات، يجب تحديد نوعها بـ var (int, string, bool...)
د. يجب أن تشير الدالة إلى معلماتها وقيمتها المرجعة من خلال علامات المعلمات والإرجاع
هـ. بالنسبة للكلمات الرئيسية التي تظهر مرتين أو أكثر، تجاهل الكلمات الرئيسية الزائدة عن الحاجة واحتفظ بواحدة فقط.
و. عند استدعاء وظائف أو فئات أخرى، يجب استخدام رابط أو علامات أخرى للربط بالجزء المقابل لتسهيل قراءة المستند.
ز. استخدم التعليقات غير التوثيقية عند الضرورة لتحسين إمكانية قراءة التعليمات البرمجية.
ح. اجعل المحتوى الوصفي موجزًا وفي صلب الموضوع، باستخدام العبارات بدلاً من الجمل كلما أمكن ذلك.
i. يجب الإعلان عن المتغيرات العامة والمتغيرات الثابتة والثوابت باستخدام العلامات المقابلة لها
7. ملخص
phpDocumentor هي أداة إنشاء مستندات تلقائية قوية للغاية، ويمكن أن تساعدنا في كتابة تعليقات موحدة وإنشاء مستندات سهلة الفهم ومنظمة بشكل واضح، وهو أمر مفيد جدًا في ترقيات التعليمات البرمجية والصيانة والتسليم وما إلى ذلك.
للحصول على وصف أكثر تفصيلاً لـ phpDocumentor، يمكنك الذهاب إلى موقعه الرسمي على الإنترنت
http://manual.phpdoc.org/View
8. الملحق الملحق 1:
الكلمات الرئيسية التي تم التعرف عليها بواسطة phpdoc:
يشمل
يتطلب
include_once
require_once
يُعرِّف
وظيفة
عالمي
فصل
الملحق 2
العلامات التي يمكن استخدامها في المستندات
<ب>
<الرمز>
<ر>
<كدب>
<لي>
<قبل>
<ul>
<سامب>
<فار>
الملحق 3:
جزء من كود php مع التعليقات الأساسية:
<?php
/**
* نموذج الملف 2، phpDocumentor Quickstart
*
* يوضح هذا الملف المعلومات الغنية التي يمكن تضمينها فيه
* التوثيق داخل الكود من خلال DocBlocks والعلامات.
* @author جريج بيفر < [email protected] >
* @الإصدار 1.0
* @ عينة الحزمة
*/
// ملف العينة رقم 1
/**
* تضمين قيمة وهمية لتوضيح قوة التحليل لـ phpDocumentor
*/
include_once 'sample3.php';
/**
* إعلان متغير عالمي خاص DocBlock
* @العدد الصحيح العالمي $GLOBALS['_myvar']
* @اسم $_myvar
*/
$GLOBALS['_myvar'] = 6;
/**
*الثوابت
*/
/**
*الثابت الأول
*/
تعريف('اختبار', 6);
/**
*الثابت الثاني
*/
تعريف('anotherconstant', strlen('hello'));
/**
* نموذج docblock للوظيفة
* توثق السلسلة العالمية حقيقة أن هذه الوظيفة تستخدم $_myvar
* @staticvar عدد صحيح $staticvar هذا هو في الواقع ما تم إرجاعه
* @param اسم سلسلة $param1 للإعلان
*param string $param2 قيمة الاسم
* @return عدد صحيح
*/
الدالة firstFunc($param1, $param2 = 'اختياري') {
ثابت $staticvar = 7؛
عالمي $ _myvar؛
إرجاع $staticvar؛
}
/**
* فئة المثال الأول، موجودة في نفس الحزمة مثل
* الأمور الإجرائية في بداية الملف
* @ عينة الحزمة
*فئات الحزمة الفرعية
*/
فئة ماي كلاس {
/**
* نموذج لمتغير خاص، يمكن إخفاؤه باستخدام --parseprivate
*خيار
* @accessprivate
* @var عدد صحيح|سلسلة
*/
فار $firstvar = 6;
/**
* @link http://www.example.com رابط المثال
* @انظر ماي كلاس ()
* @uses test، ثابت آخر
* @var array
*/
فار $ Secondvar =
صفيف (
"الأشياء" =>
صفيف (
6,
17,
"المدرع"
)،
اختبار => ثابت آخر
);
/**
* يقوم المنشئ بإعداد {@link $firstvar}
*/
وظيفة ماي كلاس () {
$this->firstvar = 7;
}
/**
* قم بإرجاع شيء بناءً على $paramie
* @param boolean $paramie
* @return عدد صحيح|babyclass
*/
وظيفة الوالدين($paramie) {
إذا (بارامي) {
العودة 6؛
} آخر {
إرجاع فئة أطفال جديدة؛
}
}
}
/**
* @ عينة الحزمة 1
*/
فئة babyclass تمتد myclass {
/**
* الجواب على الحياة والكون وكل شيء
* @var عدد صحيح
*/
فار $ Secondvar = 42؛
/**
* قيم التكوين
* @var array
*/
فار $thirdvar;
/**
* يستدعي المُنشئ الأصلي، ثم يزيد {@link $firstvar}
*/
وظيفة بيبي كلاس () {
الأصل::myclass();
$this->firstvar++;
}
/**
* يؤدي هذا دائمًا إلى إرجاع فئة myclass
* @param تجاهل $paramie
* @return myclass
*/
وظيفة الوالدين($paramie) {
إرجاع صفي الجديد؛
}
}
?>