آشنایی با استاندارد کامنت‌گذاری 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 را روی سیستم نصب نموده و مستنداتی کاربرپسند برای پروژه‌های نوشته‌شده با زبان پی‌اچ‌پی تولید نمود.

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

راهنمای نصب PhpDoc

به منظور نصب این ابزار، توصیه می‌شود که از نسخهٔ PHP 5.3.3 به بالا استفاده شود مضاف بر این که به اِکستنشن intl نیز نیاز خواهد بود. همچنین نیاز به پکیجی تحت عنوان Graphviz خواهیم داشت که به منزلهٔ نرم‌افزاری برای ساخت گراف می‌باشد. پیش از هر چیز، این نرم‌افزار را در پلتفرم گنو/لینوکس از طریق کامند زیر نصب می‌کنیم:

$ sudo apt-get install graphviz

در ادامه و به منظور نصب PhpDoc، که خود یک سری وابستگی هم دارا است، وارد پوشهٔ‌ phpdoc شده و در محیط کامندلاین دستور زیر را وارد می‌کنیم:

/var/www/oop/phpdoc$ composer require "phpdocumentor/phpdocumentor:2.*"

چنانچه کامند فوق بدون هیچ‌ گونه مشکلی پایان پذیرد، خواهیم دید که فایل composer.json به صورت زیر آپدیت خواهد شد:

{
    "autoload": {
        "psr-4": {
            "SokanAcademy\\": "classes"
        }
    },
    "require": {
        "phpdocumentor/phpdocumentor": "2.*"
    }
}

در زمان نگارش این آموزش، میان وابستگی‌های این ابزار کانفلیکت (تداخل) وجود داشته و بالتبع از روش زیر برای نصب موفقیت‌آمیز PhpDoc استفاده نمودیم اما پیش از هر چیز، نیاز است تا پکیجی که پیش از این نصب نموده‌ بودیم را حذف کنیم که برای همین منظور، ابتدا کامند زیر را اجرا می‌کنیم:

/var/www/oop/phpdoc$ composer remove "phpdocumentor/phpdocumentor"

در ادامه، مجدد کامند زیر را به منظور نصب پکیج jms اجرا می‌کنیم:

/var/www/oop/phpdoc$ composer require "jms/serializer:1.7.*"

سپس مجدد دستور زیر را برای نصب پکیج phpdocumentor اجرا می‌کنیم:

/var/www/oop/phpdoc$ composer require "phpdocumentor/phpdocumentor:2.*"

تا این مرحله از آموزش، ابزارهای مورد نیاز برای استفاده از PhpDoc نصب شده است و در ادامه خواهیم دید که به چه شکل می‌توان این کار را انجام داد. اساساً PhpDoc را می‌توان به منظور مستندسازی موارد زیر مورد استفاده قرار داد:

- پراپرتی
- کانستنت
- اینترفیس
- تِرِیت
- کلاس
- متد
- فایل
- دستورات include و require

حال برای شروع، داخل پوشهٔ classes فایلی به نام User.php ساخته و آن را به صورت زیر تکمیل می‌کنیم:

<?php
namespace SokanAcademy;

/**
 * This is class to test PhpDoc.
 * In this class, we will have different methods that are specific to different tastks
 * and are all well-documented
 */
class User
{
    public function doSomething()
    {
        // statements
    }
}

همان‌طور که ملاحظه می‌شود، کلاسی ساخته‌ایم تحت عنوان User و برای آن یک کامنت از جنس DocBlock در نظر گرفته‌ایم. برای شروع،‌ قصد داریم تا کامند phpdoc را به منظور ساخت مستندات اجرا کنیم که برای این منظور، از طریق آپشن‌های d- و f- که به ترتیب مرتبط با آدرس دایرکتوری و فایل هستند، سورسی که قصد داریم برایش مستندات بسازیم را مشخص می‌سازیم. به طور مثال، در ارتباط با پروژه‌ای که ساخته‌ایم، کامند زیر را مورد استفاده قرار می‌دهیم:

/var/www/oop/phpdoc$ ./vendor/bin/phpdoc -d ./classes

برای اجرای این ابزار، مسیر vendor/bin/phpdoc/. که فایل اجرایی PhpDoc است را وارد کرده سپس آپشن d- که مشخص‌کنندهٔ دایرکتوری هدف است را در نظر گرفته‌ایم سپس مسیر پوشهٔ classes را وارد کرده‌ایم چرا که کلیهٔ کلاس‌های پروژه داخل این فولدر خواهند بود و در صورتی که همه چیز به درستی اجرا گردد، پوشه‌ای در مسیر روت پروژه تحت عنوان output ساخته شده و مستندات داخل آن ساخته می‌‌شوند اما اگر بخوایم تا مستندات پروژه در پوشه‌ٔ مد نظر خودمان ریخته شوند، ابتدا به طور مثال پوشه‌ای به نام docs ساخته سپس کامند زیر را اجرا می‌کنیم:

/var/www/oop/phpdoc$ ./vendor/bin/phpdoc -d ./classes -t ./docs

همان‌طور که ملاحظه می‌شود، پس از آپشن t- آدرس پوشهٔ مد نظرمان را وارد کرده‌ایم و در صورت اجرای کامند فوق، کلیهٔ مستندات داخل پوشهٔ docs ساخته خواهند شد. حال اگر به داخل پوشهٔ docs نگاهی بیندازیم، خواهیم داشت:

docs
├── classes
│   └── SokanAcademy.User.html
├── css
│   ├── bootstrap-combined.no-icons.min.css
│   ├── font-awesome.min.css
│   ├── jquery.iviewer.css
│   ├── phpdocumentor-clean-icons
│   │   ├── fonts
│   │   │   ├── phpdocumentor-clean-icons.dev.svg
│   │   │   ├── phpdocumentor-clean-icons.eot
│   │   │   ├── phpdocumentor-clean-icons.svg
│   │   │   ├── phpdocumentor-clean-icons.ttf
│   │   │   └── phpdocumentor-clean-icons.woff
│   │   ├── lte-ie7.js
│   │   ├── Read Me.txt
│   │   └── style.css
│   ├── prism.css
│   └── template.css
├── files
│   ├── User.html
│   └── User.php.txt
├── font
│   ├── FontAwesome.otf
│   ├── fontawesome-webfont.eot
│   ├── fontawesome-webfont.svg
│   ├── fontawesome-webfont.ttf
│   └── fontawesome-webfont.woff
├── graphs
│   ├── classes.svg
│   └── class.html
├── images
│   ├── apple-touch-icon-114x114.png
│   ├── apple-touch-icon-72x72.png
│   ├── apple-touch-icon.png
│   ├── custom-icons.svg
│   ├── favicon.ico
│   ├── hierarchy-item.png
│   ├── icon-class-13x13.png
│   ├── icon-class.svg
│   ├── icon-interface-13x13.png
│   ├── icon-interface.svg
│   ├── icon-trait-13x13.png
│   ├── icon-trait.svg
│   └── iviewer
│       ├── grab.cur
│       ├── hand.cur
│       ├── iviewer.rotate_left.png
│       ├── iviewer.rotate_right.png
│       ├── iviewer.zoom_fit.png
│       ├── iviewer.zoom_in.png
│       ├── iviewer.zoom_out.png
│       └── iviewer.zoom_zero.png
├── index.html
├── js
│   ├── bootstrap.min.js
│   ├── html5.js
│   ├── jquery-1.11.0.min.js
│   ├── jquery.dotdotdot-1.5.9.js
│   ├── jquery.dotdotdot-1.5.9.min.js
│   ├── jquery.iviewer.js
│   ├── jquery.iviewer.min.js
│   ├── jquery.mousewheel.js
│   ├── jquery.smooth-scroll.js
│   ├── prism.min.js
│   └── ui
│       └── 1.10.4
│           └── jquery-ui.min.js
├── namespaces
│   ├── default.html
│   └── SokanAcademy.html
├── phpdoc-cache-2e
│   └── phpdoc-cache-settings.dat
├── phpdoc-cache-48
│   └── phpdoc-cache-file_bef35bc6de859859507c7891b097cd0e.dat
└── reports
    ├── deprecated.html
    ├── errors.html
    └── markers.html

همچنین لازم به یادآوری است که جهت دریافت راهنمای این ابزار در محیط کامندلاین، می‌توان دستور زیر را اجرا کرد:

/var/www/oop/phpdoc$ ./vendor/bin/phpdoc -h

داخل پوشهٔ docs فایلی است تحت عنوان index.html که با اجرای آن در مرورگر با صفحهٔ زیر روبه‌رو خواهیم شد:

حال به منظور آشنایی بیشتر با نحوهٔ استفاده از ابزار PHPDoc، کلاس User را به صورت زیر آپدیت می‌کنیم:

<?php
namespace SokanAcademy;

/**
 * This is class to test PhpDoc.
 * In this class, we will have different methods that are specific to different tastks
 * and are all well-documented
 */
class User
{
    /**
     * @version 0.0.1
     * @license SokanAcademy License
     * @link https://sokanacademy.com/terms
     * @copyright 2019
     * @author Behzad Moradi
     * @return string
     */
    public function returnUserName(): string
    {
        return "Behzad";
    }
}

همان‌طور که ملاحظه می‌شود، متدی نوشته‌ایم به نام ()returnUserName که این وظیفه را دارا است تا یک استرینگ را ریترن کند و همان‌طور که در آموزش آشنایی با مفهوم Return Type Declaration در زبان PHP توضیح دادیم، ریترن تایپ این متد استرینگ خواهد بود. در DocBlock این متد هم از تگ‌هایی همچون version@ و license@ و غیره استفاده نموده‌ایم و اگر مجدد کامند زیر را اجرا کنیم:

/var/www/oop/phpdoc$ ./vendor/bin/phpdoc -d ./classes -t ./docs

سپس به پوشهٔ docs داخل مسیر روت پروژه مراجعه کرده و فایل index.html را داخل مرورگر اجرا کنیم، خواهیم دید که دیتای این متد در زیرشاخهٔ کلاس User به درستی مستندسازی شده است (جهت آشنایی بیشتر با متدهای PHPDoc می‌توانید به لینک Tag Reference مراجعه نمایید.)

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