PHPDoc

من ويكيبيديا، الموسوعة الحرة
اذهب إلى: تصفح، ‏ ابحث

يعتبر PHPDoc معيار رسمي لصيغة كتابة التعليقات على لغة البرمجة PHP، وهو مماثل لمعيار Javadoc المتبع في لغة البرمجة Java. كما يمكن لبرمجيات التوثيق مثل phpDocumentor من إنشاء توثيق للكود مطابق لهذا المعاير ويساعد بعض بيئات التطوير IDE مثل Zend Studio, NetBeans, JetBrains PhpStorm, ActiveState Komodo Edit and IDE, PHPEdit and Aptana Studio في توضيح نوع المتغير ( variable types ) وكذلك توضيح اي امر غير مفهوم في الكود، وبإتباع هذا المعيار يكون الكود البرمجي سهل التطوير والتنقيح ويسهل على المبرمجين الاخرين سهولة قراءة الكود وفهم فحواه.

كما يدعم PHPDoc البرمجة الكائنية object-oriented بالإضافة إلى البرمجة الإجرائية procedural.

تم إصدار PHPDoc في 3 من ديسمبر عام 2000 ويمكن الإستعانة ببعض البرمجيات لكتابة معيار التعليقات هذا مثل phpDocumentor و Doxygen.

في 13 أغسطس من عام 2013 بدأت اطر العمل PHP Framework بالأعتماد على PHPDoc كمعيار لكتابة التعليقات.

أنواع التعليقات في PHPDoc[عدل]


التعليق على أكثر من سطر DocBlock

التعليق على أكثر من سطر في لغة البرمجة PHP مشابه تماما للغة البرمجة C++ حيث يبدأ التعليق بـ /** ثم في كل سطر يكون رمز النجمة * وينتهي التعليق بـ */ .

يتم كتابة هذا النوع من التعليقات قبل الكود المراد وصفة.

أي سطر جديد في التعليق لا يبدأ بعلامة النجمة * يعتبر مخالف لمعيار PHPDoc.

في هذا المثال تم تطبيق التعليق على أكثر من سطر DocBlcok على الدالة المسماه foo() ولاحظ ان التعليق تم كتابته قبل تعريف الدالة.

/**
 * This is a DocBlock comment
 */
function foo()
{
}


وفي هذا المثال تم تطبيق التعليق على أكثر من سطر DocBlock على الثابت المسمى aklo، مما يعني ان هذا التعليق لا علاقة له بالدالة foo

/**
 * DocBlock for function foo?
 *
 * No, this will be for the constant aklo!
 */
define('aklo',2);
function foo($param = aklo)
{
}

يستخدم التعليق على أكثر من سطر لوصف :

define() statements, functions, classes, class methods, and class vars, include() statements, and global variables

التعليق على أكثر من سطر DocBlock يجب ان يحتوي على النقاط التالية :

  • وصف مختصر Short Description.
  • وصف مفصل Long Description.
  • عناوين محدده Tags.