php doc comment وطريقة كتابتها في laravel

تعتبر تعليقات PHP Doc طريقة لإضافة الوثائق إلى كود PHP . يمكن استخدامه من خلال كتابة شرطة مائلة وعلامتين نجميتين (/ **) في البداية وعلامة النجمة والشرطة المائلة للأمام (* /) في النهاية. هذه التعليقات غير مرئية في إخراج البرنامج أي لا يتم تنفيذها وليس لها نتيجة، ولكن يمكن استخدامها لإنشاء وثائق باستخدام أدوات مثل phpDocumentor. ضمن التعليق ، يمكنك استخدام tags خاصة ، مثلparam وreturn ، لوصف الوظيفة ومعلماتها وقيمة الإرجاع الخاصة بها, على سبيل المثال

/** This function adds two numbers
*
* @param int $a The first number
* @param int $b The second number
*
* @return int The sum of the two numbers
*/
function add($a, $b) {
    return $a + $b;
}```

في المثال السابق يوجد دالة لارجاع مجموع عددين, وقمنا بكتابة تعليق يشرح الهدف من هذه الدالة, واستخدمنا العلامة الخاصة param التي نصف بها المعاملات التي استخدمناها في الدالة وهما المعامل $a والمعامل $b واستخدمنا العلامة الخاصة return لوصف ما هو الراجع من الدالة, لا يتم تنفيذ هذه التعليقات وتستخدم فقط لغرض التوثيق حيث تساعد المطورين على فهم الغرض من الوظيفة ، والمعلمات ، وقيمة الإرجاع ، مما يسهل قراءة التعليمات البرمجية والحفاظ عليها ومراجعتها.

بالإضافة للتعليق السابق تحتاج لإضافة التعليقات في الكود للعديد من الفوائد منها 

• لجعل الآخرين  يفهمون التعليمات البرمجية الخاصة بك (مفيدة جداً إذا كنت تعمل ضمن فريقعمل)
• ذكّر نفسك بما فعلته - لقد جرب معظم المبرمجين العودة إلى عملهم بعد عام أو عامين واضطرارهم إلى إعادة اكتشاف ما فعلوه. يمكن أن تذكرك التعليقات بما كنت تفكر فيه عندما كتبت الكود

يمكنك استخدام التعليقات من خلال php عن طريق 

<?php
// تعليق سطر واحد

# تعليق سطر واحد
?>

/*
تعليق يمكن أن
يكون على 
عدة أسطر
*/

و يمكنك استخدام التعليقات من خلال laravel blade عن طريق 

{{-- This comment will not be in the rendered HTML --}}

مثلما اشار المدربون فإن طريقة اضافة تعليق في PHP تختلف، نعني بـ Doc comment النوع الاخير الذي يبدوا كـ:

/**
*
 */

التعليق الذي يحتويه هذا النوع يسمى DocBlock وهو نوع من التعليقات التي يمكن أن توفر معلومات مطولة حول عنصر او جزئية ما في التعليمات البرمجية الخاصة بك. وذلك اما للمطورين الذين سيشتغلون مستقبلا على هاته الشيفرة او حتى لبيئات التطوير المتكاملة IDEs من مثل VS code التي تستعمل قواعد كتابة هذا التعليق في توثيق الشيفرة وفي توثيق الواجهات البرمجية.

وعموما، يتكون هذا التعليق من:

• الملخص Summary وهو شرح موجز لما ستقوم به الجزئية المراد توضيحها.
• التوصيف Description وهو شرح اكثر تفصيلا لما ستقوم به الجزئية.
• الوسوم Tags وهي سلسلة من التوصيفات الاخرى التي تسبق برمز @ وتعبر عن معلومات من مثل عائد الدالة او نوع المعاملات او غيرها.

لاحظ المثال:

/**
* .حساب العمر انطلاقا من تاريخ الميلاد
* 
* تستعمل هاته الدالة الكائن كذا وكذا في حساب 
* الفارق الزمني بين كذا وكذا 
*
* @see path/to/resource.php
* @param {string} $date_of_birth
* @return integer
*/
function getAge($date_of_birth){

}