آشنایی با استاندارد کامنت‌گذاری PHPDoc


PHPDoc استانداردی الهام‌گرفته از Javadoc به منظور کامنت‌گذاری سورس‌کدهای نوشته‌شده با زبان پی‌اچ‌پی است که از ده‌ها تگ مختلف برخوردار است که برخی از آن‌ها عبارتند از:

@api
@author
@category
@copyright
@deprecated
@example
@filesource
@global
@ignore
@internal
@license
@link
@method
@package
@param
@property
@property-read
@property-write
@return
@see
@since
@source
@subpackage
@throws
@todo
@uses & @used-by
@var
@version

همچنین PHPDoc این امکان را در اختیار برخی نرم‌افزارها همچون Zend Studio ،NetBeans و PhpStorm قرار می‌دهد تا قابلیت‌هایی همچون تکمیل کد،‌ تایپ هینتینگ و دیباگینگ را برای توسعه‌دهندگان بهبود بخشند. PHPDoc هم برای کدنویسی به سَبک Procedural و هم OOP استفاده می‌شود که در این آموزش مورد دوم را مورد بررسی بیشتر قرار خواهیم داد.

آشنایی با مفهوم DocBlock

DocBlock کامنتی است که با علائم **/ شروع شده سپس در ابتدای هر خط یک علامت *  قرار گرفته و در پایان نیز علامت /* نوشته می‌شود. به عنوان مثال داریم:

/**
 * This is a DocBlock comment
 */
public function doSomething()
{

}

چیزی که در ارتباط با کامنت فوق حائز اهمیت است این که کامنت‌هایی از این دست می‌باید بلافاصله قبل از فانکشن نوشته شوند. اساساً هر DocBlock از سه بخش تشکیل شده است که عبارتند از:

- توضیحات کوتاه (معمولاً با یک نقطه در انتهای جمله یا یک اینتر مشخص می‌گردد.)
- توضیحات بلند
- تگ‌ها

به عنوان نمونه، مثال زیر دربرگیرندهٔ هر سه بخش فوق است:

 <?php
 /**
  * A summary informing the user what the associated element does.
  *
  * A *description*, that can span multiple lines, to go _in-depth_ into the details of this element
  * and to provide some background information or textual references.
  *
  * @param string $myArgument With a *description* of this argument, these may also
  *    span multiple lines.
  *
  * @return void
  */
public function myFunction($myArgument)
{
  
}

همان‌طور که ملاحظه می‌شود، تگ‌ها در این استاندارد کامنت‌نویسی با علامت @ شروع می‌شوند که به منزلهٔ متادیتایی هستند که اطلاعات بیشتری در ارتباط با یک متد می‌دهند. به طور مثال،‌ تگ author@ به منظور درج نام توسعه‌دهنده مورد استفاده قرار می‌گیرد و تگی همچون link@ به منظور لینک دادن به سایت یا ریپازیتوری مرتبط با سورس‌کد مد نظر است (لازم به یادآوری است که از تگ‌‌های اچ‌تی‌ام‌ال می‌توان در توضیحاتی که داخل کامنت آمده‌اند استفاده نمود.)

پس از این معرفی کوتاه، در ادامهٔ این آموزش خواهیم دید که به چه شکل می‌توان PhpDoc را روی سیستم نصب نموده و مستنداتی کاربرپسند برای پروژه‌های نوشته‌شده با زبان پی‌اچ‌پی تولید نمود.

این بخش از محتوا مخصوص کاربرانی است که ثبت‌نام کرده‌اند.
جهت مشاهدهٔ این بخش از محتوا لاگین نمایید.

جمع‌بندی
زمانی که از یکسو پروژه‌ای به مرور زمان حجیم و در عین حال پیچیده می‌شود و از سوی دیگر چندین و چند توسعه‌دهندهٔ مختلف شروع به کار روی آن می‌کنند، این نیاز احساس می‌گردد تا سورس‌کد پروژه را مستندسازی نمود تا در آینده اعضای تیم مهندسی با کمترین میزان سردرگمی مواجه گردند که در همین راستا می‌توان از ابزار رایگان PHPDoc استفاده نمود.

دانلود فایل‌های تمرین

لیست نظرات
کاربر میهمان
دیدگاه شما چیست؟
کاربر میهمان