بي أتش بي دوك
بدايةً، بي أتش بي دوك هو معيار رسمي لصيغة كتابة التعليقات على لغة البرمجة بي إتش بي، وهو مماثل لمعيار جافا دوك المتبع في لغة البرمجة جافا. كما يمكن لبرمجيات التوثيق مثل phpDocumentor من إنشاء توثيق للكود مطابق لهذا المعاير ويساعد بعض بيئات التطوير المتكاملة مثل: زند ستوديو، نت بينز، بي إتش بي ستورم، كومودو اديت، بي إتش بي اديت، وابتانا ستوديو، في توضيح نوع المتغير وكذلك توضيح أي امر غير مفهوم في الكود، وبإتباع هذا المعيار يكون الكود البرمجي سهل التطوير والتنقيح ويسهل على المبرمجين الآخرين قراءة الكود وفهم فحواه. وتعرض الأقسام التالية جوانب أخرى من الموضوع.
من جهة ثانية، كما يدعم PHPDoc البرمجة الكائنية فضلًا عن البرمجة الإجرائية.
علاوةً على ذلك، في 13 أغسطس من عام 2013 بدأت اطر العمل PHP Framework بالأعتماد على PHPDoc كمعيار لكتابة التعليقات.
وفي السياق ذاته، تم إصدار PHPDoc في 3 من ديسمبر عام 2000 ويمكن الاستعانة ببعض البرمجيات لكتابة معيار التعليقات هذا مثل phpDocumentor ودي أكسجين.
أنواع التعليقات في PHPDoc
التعليق على أكثر من سطر DocBlock
وفي السياق ذاته، أي سطر جديد في التعليق لا يبدأ بعلامة النجمة * يعتبر مخالف لمعيار PHPDoc.
وفي السياق ذاته، التعليق على أكثر من سطر في لغة البرمجة PHP مشابه تماما للغة البرمجة C++ حيث يبدأ التعليق بـ /** ثم في كل سطر يكون رمز النجمة * وينتهي التعليق بـ */ .
يتم كتابة هذا النوع من التعليقات قبل الكود المراد وصفة.
وعلى صعيد آخر، في هذا المثال تم تطبيق التعليق على أكثر من سطر DocBlcok على الدالة المسماة foo ولاحظ ان التعليق تم كتابته قبل تعريف الدالة.
- /**
- * This is a DocBlock comment
- */
- function foo
- {
}
- التعليق على أكثر من سطر DocBlock يجب ان يحتوي على النقاط التالية:
- وصف مختصر.
- وصف مفصل.
- عناوين محدده Tags.
في هذا الإطار، define statements, functions, classes, class methods, and class vars, include statements, and global variables
يستعمل التعليق على أكثر من سطر لوصف:
define('aklo',2);
{
function foo($param = aklo)
/**
* DocBlock for function foo?
*
*/
* No, this will be for the constant aklo!
}
علاوةً على ذلك، وفي هذا المثال تم تطبيق التعليق على أكثر من سطر DocBlock على الثابت المسمى aklo، مما يعني ان هذا التعليق لا علاقة له بالدالة foo
📝 هل في هذه المقالة خطأ؟
إذا وجدت معلومة تحتاج تصحيحاً أو إضافة، أو أردت حذف المقالة، أرسل لنا طلباً وسنراجعه.
ما رأيك في هذه المقالة؟