راهنمای مستندسازی با phpdoc

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

PhpDoc ابزار قدرتمند مستندسازی

کامنت‌نویسی کاربردهای زیادی دارد، که می‌توان از مهمترین موارد استفاده آن به خطایابی و راهنمای برنامه‌نویسان برای تجزیه و تحلیل و توسعه سریعتر کدها اشاره نمود. در ادامه به بررسی یکی از قویترین ابزارهای مستندسازی یعنی phpdoc که چارچوبی برای تحلیل و توسعه راحت‌تر کدها است می‌پردازیم، مثلا یک فانکشن داریم و می‌خواهیم از آن در بخش دیگری از برنامه استفاده کنیم، پس تنها دانستن کار آن کافیست و نیازی به دانستن نحوه کار آن نداریم، phpdoc اینکار را برای ما راحت‌تر می‌کند.

PhpDoc چیست؟

PhpDoc اقتباسی از JavaDoc برای زبان برنامه نویسی php است. این ابزار هنوز یک استاندارد غیررسمی برای کامنت‌گذاری کدهای PHP است، اما در هنگام نگارش این مطلب، در حال طی فرآیند رسمی شدن است. phpDoc هم از کدهای شی‌گرا و هم رویه‌گرا پشتیبانی می‌کند. phpdoc ابزاری قدرتمند است که به شما اجازه می‌دهد که به آسانی کدهای خود را در کامنت‌هایی با الگوی خاص مستندسازی نمایید. این مستندات علاوه بر اینکه در سورس کدهای شما در دسترس است در مستندات حرفه‌ای استخراج شده با استفاده از رابط وب و خط فرمان نیز در دسترس هستند. نتیجه می‌تواند در فرمت‌های مختلفی از جمله pdf، html و chm تولید شود. به علاوه، بسیاری از IDEها مانند Zend Studio و PHP Storm قابلیت تکمیل کد را دارند که می‌توانند کامنت‌های phpdoc را تجزیه و تحلیل نموده و ویژگی‌های مفیدی مانند type-hinting را فراهم می‌کند.

DocBlocks

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

<?php
/**
 * Calculates sum of squares of an array
 *
 * Loops over each element in the array, squares it, and adds it to
 * total. Returns total.
 *
 * This function can also be implemented using array_reduce();
 *
 * @param array $arr
 * @return int
 * @throws Exception If element in array is not an integer
 */
function sumOfSquares($arr) {
    $total = 0;
    foreach ($arr as $val) {
        if (!is_int($val)) {
            throw new Exception("Element is not an integer!");
        }
        $total += $val * $val;
    }
    return $total;
}

DocBlockها شامل سه بخش زیر هستند:

چکیده(Summary)

چکیده یا توضیح کوتاه یک توضیح مختصر است که در شرایط زیر به اتمام می‌رسد. 1. با یک خط خالی بعد از آن:

/**
 * This is a summary
 *
 * This is a description
 */

2. با یک نقطه در انتها که با یک خط جدید دنبال می شود:

/**
 * This is a summary.
 * This is a description
 */

PhpDoc مسیرها را هوشمندانه تجزیه و تحلیل می‌کند و فقط در صورتی توضیحات کوتاه را به پایان می‌رساند که نقطه در پایان یک جمله باشد. کاربرد: مقدمه‌ای کوتاه برای عملکرد عنصر مرتبط با آن می‌نویسیم.

توضیحات (Description)

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

PhpDoc می‌تواند مستندات را در فرمت‌های چندگانه تولید کند، گرچه تگ‌های HTML لزوما مانند آنچه در فایل‌های HTML هستند رندر نمی‌شوند، فرمت‌دهی واقعی به فرمت فایلی که تولید می‌شود بستگی دارد. اگر نیاز دارید به نمایش یک تگ HTML مانند متن، از دو پرانتز مانند آنچه در مثال زیر آمده است، استفاده نمایید:

<?php
/**
 * Here an example of the italics tag: <<i>>Hello, world!<<i>>
 */

تگ‌های html پشتیبانی شده تنها استفاده از تگ‌های html لیست زیر در DocBlockها مجاز ‌است و با سایر تگ‌ها مانند متن معمولی رفتار می‌شود:

• تگ <b> برای برجسته و توپر کردن متن استفاده می‌شود.
• کدهای PHP را داخل تگ <code> در DocBlock بنویسید، تا به صورت متفاوت از متن معمولی نمایش داده شوند.
• تگ <br> مانند کاربردش در html باعث شکستن خط و رفتن به خط بعد می‌شود.
• برای کج کردن و نشانه‌گذاری متن به عنوان متن با اهمیت، از تگ <i> استفاده کنید.
• تگ <kbd> برای نمایش ورودی صفحه کلید را نشان می‌دهد.
• از تگ‌های <ol> و <ul> به ترتیب برای ساختن لیست‌های ترتیبی و غیرترتیبی و از تگ <li> برای ساخت آیتم‌های لیست استفاده کنید.
• از تگ <p> برای نمایش پاراگراف متن استفاده می‌شود.
• تگ <samp> برای نمایش نمونه ها و مثال (غیر php) استفاده می‌شود.
• تگ <pre> این تگ تمام فاصله‌ها و شکستگی خطوط را حفظ می‌کند و با تمام تگ‌ها مانند متن معمولی رفتار می‌کند.
• تگ <var> نام یک متغییر را نشان می‌دهد.

توجه: مانند استفاده در html تمام تگ‌های بالا به جز <br> باید دارای تگ پایانی باشند. PhpDoc به صورت خودکار لیست‌های متنی در توضیحات و چکیده‌ها را تشخیص می‌دهد و آن ها را تجزیه و تحلیل می‌کند. با این حال، لیست‌های تودرتو را به خوبی تجزیه و تحلیل نمی‌کند. اگر می‌خواهید از لیست‌های تودرتو استفاده کنید، بهتر است از تگ‌های HTML استفاده نمایید. مثال زیر این استفاده را به خوبی نشان می‌دهد:

/**
 * DocBlock with nested lists
 * in the tag descriptions
 * @todo My Simple TODO List
 *     - item 1
 *     - item 2
 *     - item 3
 * @todo My Complex TODO List
 *     <ol>
 *       <li>item 1.0</li>
 *       <li>item 2.0</li>
 *       <li>item 3.0</li>
 *         <ol>
 *           <li>item 3.1</li>
 *           <li>item 3.2</li>
 *         </ol>
 *       <li>item 4.0</li>
 *     </ol>
 */

تگ‌ها

بخش تگ یک DocBlock شامل هر تعدادی از تگ‌هایی است که با علامت @ شروع می‌شوند. تگ‌ها برای دادن اطلاعات اضافی از جمله پارامترهای مورد نیاز و نوع آن‌ها استفاده می‌شوند. اغلب تگ‌ها باید در خط خودشان باشند به استثنای تگ‌های مشخص که ممکن است به صورت خطی باشند.  تگ‌های خطی با کروشه } مشخص شده‌اند و ممکن است در هر دو نوع توضیحات و چکیده‌ها باشند. در ادامه لیست کامل این تگ‌ها را بررسی خواهیم نمود. کاربرد: تگ‌ راهی هست تا بتوان به طور مختصر و یکسان اطلاعات فراوانی درباره عنصر مرتبط بدست آورد. برای مثال نوع اطلاعاتی را که توسط هر تابع یا متد برگردانده می‌شود را توصیف می‌کند. برای اینکه تگ‌ها تجزیه و تحلیل شوند باید اولین چیزی باشند که در هر خط می‌آیند. و هر تگی که PhpDocumentor نتواند بشناسد آن را به صورت متن معمولی نمایش می‌دهد. پس ما دو نوع تگ داریم، تگ‌های html که در توضیحات و چکیده‌ها قابل استفاده هستند و تگ‌های PhpDoc که با علامت @ می‌آیند و در بخش تگ‌ها قرار می‌گیرند. تگ‌های درون خطی (Inline) در جریان متن جایی که ظاهر می‌شوند، نمایش داده می‌شوند و از توضیحات جدا نیستند. مثال از 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
  */
  function myFunction($myArgument)
  {
  }

توضیح DocBlock بالا: خط 2 : استفاده از تگ کامنت گذاری چند خطی با دو ستاره /** برای شروع DocBlock استفاده شده است. خط 3: مثالی از چکیده است. معمولا چکیده یک خطی است ولی می‌تواند چندین خط را تا پایان دادن به آن دربرگیرد، در بخش قبل توضیح داده شد. خط 5 و 6: مثالی برای توضیحات است که می‌تواند محدوده خطوط چندگانه را شامل شود و به آن‌ها توضیحات توصیفی و توضیحات بلند نیز می‌گویند. خط 8 و 9: نشان می‌دهد که شما می‌توانید تگ‌ها را در DocBlock وارد کنید تا اطلاعات بیشتری درباره عنصر فراهم آورید. در مثال بالا آرگومان $myArgument تعریف شده است و نوع آن (رشته)، را با یک توضیح درباره این آرگومان توصیف می‌کند. خط 11: این خط مشخص می‌کند که مقدار بازگشتی عنصر مرتبط void است، یعنی هیچ مقداری برنمی‌گرداند. خط 12: بستن DocBlock مشابه کامنت‌گذاری چندخطی است و با */ بسته می‌شود.

/**
 * inline tags demonstration
 *
 * this function works heavily with {@link foo()} to rule the world
 */
function bar()
{
}

function foo()
{
}

مثال بالا یک متن راهنما را به همراه لینکی در هنگام نوشتن کدها به شما نشان می‌دهد، به عکس زیر توجه نمایید:

اگر باید یک خط جدید را با نماد @ شروع کنید اما نمی‌خواهید بعنوان یک تگ تفسیر شود، می‌توانید با استفاده از یک بک اسلش \ از تفسیر آن جلوگیری نمایید.

Annotations

علاوه بر تمام موارد بالا ممکن است در هنگام دیدن DocBlockها با Annotationها روبرو شوید. یک Annotation، نوع خاصی از تگ است که نه تنها جنبه خاصی از عنصر مرتبط را مستند می‌کند، بلکه شیوه رفتار برنامه را نیز تحت تاثیر قرار می‌دهد. Annotationها در شکل‌های مختلف استفاده می‌شوند، بسیاری از آنها دقیقا مانند تگ‌های معمولی هستند اما برخی از آنها syntax پیچیده‌تری دارند:

/**
 * @ORM\Entity(repositoryClass="MyProject\UserRepository")
 */

مثال بالا نشان می‌دهد که شما چگونه نحوه نمایش یک کلاس را تعریف می‌کنید تا ماهیت یک پایگاه داده را در دکترین نشان دهد، همانطور که مشاهده می‌کنید نام برچسب به دو بخش تقسیم شده است، یک فضای نام و یک نام یادداشت واقعی. برای کسانی که با دکترین آشنایی ندارند، مجموعه‌ای از کتابخانه‌های php هستند که تمرکز اصلی آن‌ها بر سرویس‌های ذخیره‌سازی و قابلیت‌های مرتبط با آن‌ها است. یکی از ویژگی‌های کلیدی آن امکان نوشتن کوئری‌های دیتابیس به زبان DQL (یک زبان محلی شی‌گرا) است که شما را از نوشتن کوئری به زبان SQL بی نیاز می‌نماید.

تگ‌های استاندارد PhpDoc

در جدول زیر تگ‌های استاندارد قابل استفاده و محدوده عناصر قابل استفاده و توضیح کاربرد آنها نوشته شده است، دقت کنید که منظور از عنصر مرتبط، عنصری (مثلا یک تابع، متد یا فیلد) است که بدون هیچ کامنت یا کد دیگری، مستقیما زیر آن DocBlock آورده شده است:

به مثال زیر توجه کنید:

/**
 * The short description
 *
 * As many lines of extendend description as you want {@link element}
 * links to an element
 * {@link http://www.example.com Example hyperlink inline link} links to
 * a website. The inline
 * source tag displays function source code in the description:
 * {@source }
 *
 * In addition, in version 1.2+ one can link to extended documentation like this
 * documentation using {@tutorial phpDocumentor/phpDocumentor.howto.pkg}
 * In a method/class var, {@inheritdoc may be used to copy documentation from}
 * the parent method
 * {@internal
 * This paragraph explains very detailed information that will only
 * be of use to advanced developers, and can contain
 * {@link http://www.example.com Other inline links!} as well as text}}}
 *
 * Here are the tags:
 *
 * @abstract
 * @access       public or private
 * @author       Mojtaba Pakzad <info@baversion.com>
 * @copyright    name date
 * @deprecated   description
 * @deprec       alias for deprecated
 * @example      /path/to/example
 * @exception    Javadoc-compatible, use as needed
 * @global       type $globalvarname
   or
 * @global       type description of global variable usage in a function
 * @ignore
 * @internal     private information for advanced developers only
 * @param        type [$varname] description
 * @return       type description
 * @link         URL
 * @name         procpagealias
   or
 * @name         $globalvaralias
 * @magic        phpdoc.de compatibility
 * @package      package name
 * @see          name of another element that can be documented,
 *                produces a link to it in the documentation
 * @since        a version or a date
 * @static
 * @staticvar    type description of static variable usage in a function
 * @subpackage    sub package name, groupings inside of a project
 * @throws       Javadoc-compatible, use as needed
 * @todo         phpdoc.de compatibility
 * @var        type    a data type for a class variable
 * @version    version
 */
function if_there_is_an_inline_source_tag_this_must_be_a_function()
{
// ...
}

برای دیدن لیست کامل تگ‌ها و اطلاعات کامل درباره آنها راهنمای کامل تگ‌های PhpDoc را ببینید.

پکیج‌ها

پکیج‌های PhpDoc برای گروه‌بندی عناصر کد مرتبط در مستندات تولید شده استفاده می‌شوند. شما می‌توانید پکیج‌هایی را برای فایل‌ها و کلاس‌ها مشخص کنید و کدهای زیر مجموعه از آن‌ها ارث بری خواهند نمود، برای مثال اگر پکیج در DocBlock نوع file-level نوشته شود، توابع، ثابت‌ها و متغییرها از آن ارث بری می‌کنند. برای مشخص کردن یک پکیج، تگ @package را در یک DocBlock نوع file-level یا class-level (این دو مورد در بخش‌های پایین‌تر توضیح داده شده است) قرار دهید. یک نام پکیج می‌تواند شامل حروف، اعداد، خط تیره، زیرخط و براکت (] و [) باشند. مثال زیر یک پکیج فایل را تعریف می‌کند:

<?php
/**
 * This is a file-level DocBlock
 *
 * @package Some_Package
 */

اگر سطوح چندگانه‌ای از پکیج‌ها و زیر پکیج‌ها دارید، می‌توانید یک زیرپکیج را با تگ @subpackage مانند مثال زیر تعریف نمایید.

<?php
/**
 * This is a class-level DocBlock
 *
 * @package    Some_Package
 * @subpackage Other
 */
class SomeClass {
}

اگر در یک DocBlock از نوع file-level یا class-level، یک پکیج را مشخص نکند، به عنوان پکیج پیش فرض (نام پکیج پیش فرض"deafult" است) در نظر گرفته می‌شود. می‌توانید پکیج متفاوتی را در هنگام تولید مستندات با استفاده از آپشن -dn خط فرمان مشخص کنید تا به عنوان نام پکیج پیش فرض استفاده شود.  

قالب‌های DocBlock

هدف از استفاده از قالب‌های DocBlock کاهش تایپ بیش از حد است. برای نمونه، اگر تعداد زیادی از متغییرهای کلاس خصوصی (private) هستند، از یک قالب  DocBlock برای علامت‌گذاری آن‌ها به عنوان خصوصی استفاده می‌شود. قالب‌های DocBlock به سادگی هر DocBlock معمولی را که در بلاک قالب (template) پیدا کند تکمیل می‌کند. تفاوت یک قالب DocBlock با یک DocBlock در هدر آن است. ساده‌ترین قالب DocBlock:

    /**#@+
     *
     */

متنی که این DocBlock را به عنوان قالب DocBlock مشخص می‌کند "/**#@+" است، دقت کنید که هر شش کاراکتر باید باشند. قالب DocBlock به تمام عناصر قابل مستندسازی تا زمانی که به نشانگر پایان قالب برسد اعمال می‌شود:

/**#@-*/

توجه کنید که هر 8 کاراکتر "/**#@-*/" باید به ترتیب باشند تا phpDocumentor آنها را به عنوان یک پایان دهنده قالب بشناسد.  

چه چیزی قابل مستندسازی است؟

همه عناصر کد را با DocBlock نمی‌توان مستند کرد. در زیر لیستی از عناصر کدی که می‌توانند مستندسازی شوند آورده شده است:

• فایل‌ها
• کلاس‌ها
• رابط‌ها (interface)
• trait‌ها
• توابع و متدها
• فیلدهای کلاس (Class properties)
• متغییرهای سراسری
• ثابت‌ها و ثابت‌های داخل کلاس
• include()
• require()
• define()

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

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

مثال بالا یک DocBlock است که متعلق به ثابت است و برای تابع زیر آن DocBlock تعریف نشده است.

فایل‌ها

DocBlockهای File-level همان DocBlockهای معمولی هستند، تنها تفاوت آن‌ها در دو چیز است، اولین تفاوت محل قرارگیری که در اولین DocBlock هستند که در ابتدای فایل نوشته می‌شوند و مورد دوم هم نوع تگ‌های قابل استفاده در آن‌ها است که در ادامه توضیح داده‌ام، در واقع file-level برای مستندسازی محتوای یک فایل استفاده می‌شوند. بسیار توصیه می‌شود که یک DocBlock از نوع file-level را در هر فایلی که مستند می‌کنید درج کنید، و اگر یکی را در هنگام تولید مستندات درج نکنید، PhpDoc یک اخطار (warning) نمایش خواهد داد. اغلب پروژه‌ها می‌خواهند لایسنس یا تابع را به جای مستند کردن برای یک عنصر تنها، برای کل فایل مستند کنند، اینکار با آوردن DocBlock مربوطه در اول فایل قابل انجام است. مهم است که توجه داشته باشید هر زمان که یک عنصر ساختاری دیگر مستقیما DocBlock را دنبال کند، DocBlock اول از نوع file-level شناخته می‌شود اما DocBlock دوم متعلق به عنصر بعدی است. مثال زیر یک DocBlock از نوع file-level است:

<?php
/**
 * I belong to a file
 */

/**
 * I belong to a class
 */
class Def
{
}

اما مثال زیر یک DocBlock متعلق به کلاس Def است:

<?php
/**
 * I belong to a class
 */

class Def
{
}

اکثر عناصر با قرارگیری یک DocBlock قبل از عنصر مربوطه مستند می‌شوند، اما فایل‌ها یک استثنا هستند (از آنجایی که شما نمی‌توانید هیچ چیزی را قبل از یک فایل بنویسید). برای ساخت DocBlock از نوع File-level باید DocBlock مربوطه را در خطوط ابتدایی فایل قرار دهید. یک DocBlock از نوع file-level معمولا شامل تگ‌های @package و @subpackage و @license و @author هستند. تگ‌های @package و @subpackage  قبلا توضیح داده شدند. تگ @license  برای مشخص کردن یک لینک به یک لایسنس خارجی که لایسنس مربوط به کدهای‌تان را پوشش می‌دهد استفاده می‌شود، این تگ باید شامل لینک به لایسنس و یک عنوان اختیاری باشد. تگ @author برای مشخص کردن نام و ایمیل نویسنده فایل استفاده می‌شود، البته نوشتن آدرس ایمیل برنامه نویس مقابل آن در بین تگ‌های <>  و اختیاری است. برخلاف اغلب عناصر، یک DocBlock از نوع file-level باید شامل یک تگ @package باشد تا به درستی تجزیه و تحلیل شود. در ادامه یک مثال کامل از DocBlock از نوع file-level آورده شده است:

<?php
/**
 * This file contains common functions used throughout the application.
 *
 * @package    MyProject
 * @subpackage Common
 * @license    http://opensource.org/licenses/gpl-license.php  GNU Public License
 * @author     Moshe Teutsch <moteutsch@gmail.com>
 */

کلاس‌ها

یک DocBlock از نوع class-level قبل از تعریف کلاس قرار می‌گیرد و باید مقصود از کلاس را توصیف کند. DocBlock نوع class-level نیز مانند DocBlockهای نوع file-level، معمولا شامل تگ‌های @package و @subpackage و @author هستند، به مثال زیر توجه کنید:

<?php
/**
 * An example class
 *
 * The class is empty for the sake of this example.
 *
 * @package    MyProject
 * @subpackage Common
 * @author     Moshe Teutsch <moteutsch@gmail.com>
 */
class Example {
}

توابع و متدها

توابع و متدها در PhpDoc مانند هم مستندسازی می‌شوند. (برای افرادی که ممکن است با کلمات فنی آشنا نباشند، یک متد همان تابع است که در یک کلاس استفاده شده باشد.) توابع و متدها معمولا شامل تگ‌های @param و @return در DocBlockهای مربوط به خودشان هستند. تگ @param برای مستندسازی نوع مورد انتظار برای پارامتر استفاده می‌شود و شامل سه بخش است: پارامتر، نوع داده و یک توضیح اختیاری. تگ @return برای مستندسازی نوع داده برگشتی استفاده می‌شود و شامل دو بخش است: نوع داده و یک توضیح اختیاری. در هر دو تگ بالا، نوع داده می‌تواند یک نوع داده معتبر php، یک نام کلاس یا "mixed" باشد، همچنین نوع داده می‌تواند شامل چندین نوع باشد که با علامت پایپ | (pipe: با نگهداشتن shift و فشردن همزمان کلید بک اسلش \) از هم جدا شده‌اند.

<?php
/**
 * Finds and returns user by ID or username
 *
 * @param int|string $user Either an ID or a username
 * @param PDO $pdo A valid PDO object
 * @return User Returns User object or null if not found
 */
function getUser($user, PDO $pdo)
{
    // ...
    if ($isFound) {
        return new User(...);
    }
    return null;
}

تولید مستندات

هنگامی که شما کد PHP خودتان را مستند کردید، خواهید توانست مستندات کاربرپسند خود را از آن تولید کنید. برای اینکار، ابزار خط فرمان PhpDoc را اجرا کنید:

moteutsch@vivaldi:~$ phpdoc -d /path/to/files/ -t /path/to/docs/ -ti 'Documentation Title' -dn 'Default Package' -o HTML:frames:default

آپشن -d لیستی جداشده با کاما از دایرکتوری‌ها را مشخص می‌کند که شامل فایل‌هایی برای مستند است، و -t مسیر تولید مستند است. -ti برای مشخص کردن عنوان پروژه و -dn برای تنظیم نام پکیج پیش فرض استفاده می‌شود. در نهایت، -o نیز فرمت مستندسازی را مشخص می‌کند. PhpDoc یک انتخاب گسترده از فرمت‌ها برای انتخاب از بین آن ها دارد. لیست کامل را در ادامه توضیح داده شده است. می‌توانید با اجرای دستور help با استفاده از ابزار خط فرمان اطلاعات بیشتری در این مورد بدست آورید:

moteutsch@vivaldi:~$ phpdoc -h

هنگامی که دستور را اجرا می کنید، مسیر مستندات که مشخص کرده‌اید باید شامل مستندات تولید شده باشد. PhpDoc همچنین یک رابط وب برای افرادی که با رابط خط فرمان راحت نیستند، دارد. بحث درباره آن خارج از محدوده مورد بحث این پست است، اما می‌توانید در سایت رسمی PhpDoc اطلاعات بیشتری درباره آن بدست آورید.

جمع‌بندی

PhpDoc تنها یکی از ابزار مستندسازی است که دارای ویژگی‌های قدرتمند زیادی است. DocBlock به بخشی از کد گفته می‌شود که کامنت‌های ما که قرار است به مستندات تبدیل شود در آن نوشته می‌شوند و تگ‌های استاندارد DocBlock در این مطلب به صورت خلاصه در جدول مربوطه توضیح داده شدند. به شما نشان دادم که چگونه مستندات خود را با استفاده از پکیج‌ها سازماندهی نمایید. با خواندن این مطلب متوجه خواهید شد که برای کدام عناصر می‌توانید مستندات تولید کنید و تعدادی مثال از انجام آن زدم. توصیه می‌کنم که استفاده از PhpDoc را در پروژه‌هایتان آغاز نمایید، حتی اگر فقط بخش‌های مهم آن را شده مستند کنید. احتمالا به این نکته پی برده‌اید که اگر کد خود را به خوبی کامنت‌گذاری کنید، زمان زیادی را در آینده برای تحلیل و توسعه کدتان، سرمایه‌گذاری خواهید نمود.