PHPDoc، قسمت دوم – DocBlock

DocBlock یک گسترش برای توضیحات نویسی سبک C++ در PHP است که با ‘/**' شروع می شود و هیشه در ابتدار هر خط یک ‘*’ قرار می گیرد. در مستند سازی DocBlock بر همه عناصر مقدم است. هر خط در DocBlock که با ‘*’ شروع نشده باشد نادیده گرفته می شود. این یک نمونه مثال برای DocBlock است:

[php]
/**
* This is a DocBlock comment
*/
[/php]

عبارات define، توابع، کلاس ها، متد ها و خصوصیات در کلاس ها و عبارات include به همراه متغیر های سراسری همگی می توانند مستند سازی شوند. عناصر رو در کد منبع ( source code ) ببینید و مستند سازی کنید.

یک DocBlock شامل سه بخش اصلی به این شرح است:

• توضیحات کوتاه
• توضیحات بلند
• برچسب ها

توضیحات کوتاه در خط اول شروع می شود، و می تواند با یک خط خالی یا یک قاعده فسخ گردد. یک قاعده درون یک کلمه ( مانند example.com یا 0.1% ) نادیده گرفته می شود. اگر در توضیحات کوتاه طول خطوط از سه خط طولانی بیشتر باشد فقط خط اول برای توضیحات در نظر گرفته می شود.

توضیحات طولانی به دلخواه می تواند دارای خطوط بیشتر و طولانی تری باشد و علاوه برای نمایش بهتر از نشانه گذاری HTML استفاده شود.

این یک نمونه مثال برای توضیحات کوتاه و بلند در یک DocBlock است:
[php]
/**
* return the date of Easter
*
* Using the formula from 'Formulas that are way too complicated
* for anyone toever understand except for me' by Irwin Nerdy,
* this function calculates thedate of Easter given a date in the
* Ancient Mayan Calendar, if you can alsoguess the birthday of the
* author.
*/
[/php]

بطور اختیاری ممکن است همه پاراگراف ها در برچسب

قرار بگیرند.دقت کنید که اگر پاراگراف اول با برچسب

شروع نشود PHPDocumentor در حالت پیش فرض برای DocBlock یک خط خالی را برای جدا کردن پاراگراف ها در نظر می گیرد. مانند:

[php]
/**
* Short desc
*
* Long description first sentence starts here
* and continues on this line for a while
* finally concluding here at the end of
* this paragraph
*
* The blank line above denotes a paragraph break
*/
[/php]
و یک مثال هم با برچسب

[php]
/**
* Short desc
*
*

Long description first sentence starts here
* and continues on this line for a while
* finally concluding here at the end of
* this paragraph

* This text is completely ignored! it is not enclosed in p tags
*

This is a new paragraph

*/
[/php]

جزییات توضیحات در DocBlock :

در برخی از مفسر ها، تفسیر کردن توضیحات کوتاه و بلند یک DocBlock چند پرچسپ HTML برای تایین قالب بندی های اضافی را انتخاب کرده اند. از آنجا که همه برچسب های HTML مجاز نیستند، برچسب ها در فرم متن ساده یا بیشتر از برچسب های محتوایی استفاده می شود. برای نمونه برچسب را می توان به صورت در DocBlock استفاده کرد.
در اینجا می توانید مشاهده کنید لیستی از تگ هایی که توسط PHPDocumentor پشتیبانی مشوند:

	برچسب	شرح
1		تاکید - متن با حروف درشت
2		قطعه از کد PHP را محصور می کند. در برخی از مبدل ها برجسته نمایش داده می شود
3		شکستن خط. در برخی از مبدل ها نادیده گرفته می شود
4		کج - علامت گذاری به عنوان مهم
5		اشاره به صفحه کلید – صفحه نمایش
6		یک عنصر از لیست
7		ایجاد یک لیست
8		درصورت استفاده باید همه پاراگراف ها را در این برچسب محصور کنید
9		معافیت حفظ خط و فاصله، با فرض اینکه تمام تگ ها متن هستند (مانند CDATA در XML)
10		یک نمونه مشخص یا مثالها ( غیر از PHP )
11		لیست بدون ترتیب
12		معنی نام یک متغییر

در موارد نادری که یک برچسب مانند جزو متن لازم در DocBlock است باید از دو علامت مانند > برای برچسب ها استفاده کنید تا در برچسب گذاری تداخلی پیش نیاد. PHPDocumentror از حالت دوم هم پشتیبانی می کند.
استفاده از و

 :

در استفاده از این دو برچسب تمامی برچسب های HTML نادیده گرفته می شوند.