همه چیز درباره phpdoc - قسمت اول

درود بر شما. از امروز شروع میکنیم و یک سری از قسمت های آموزشی برای phpdoc رو خدمت شما اراعه میدیم. همچنین یادآوری میکنم که مطالبی که در این مقالات اشاره میشه ممکنه ۱۰۰ درصد دقیق نباشه اما تلاش بر این هست که حداکثر دقت رو داشته باشه.

برای شروع این دوره نیاز به دانش های اولیه ای هست که شامل موارد زیر میشه:

• دانش کافی درباره برنامه نویسی سمت وب
• دانش کافی درباره زبان php
• دانش کافی درباره بحث شی گرایی

مقدمه

بحث phpdoc یک الگو کامنت نویسی برای زبان php و برخی زبان های دیگه هستش که با به کارگیری اون میتونیم مستندات مربوط به هر کلاس یا متد یا ... در کد هامون رو بسازیم.

همونطور که میدونید در ابزار های کدنویسی مثل phpstorm یا vscode و ... قابلیت های خاصی برای ساختن phpdoc وجود داره که کار ما رو آسون تر میکنه. به طور مثال در phpstorm با وارد کردن کد /** و سپس اینتر میتونید به طور خودکار برای کلاس یا متد هاتون کامنت بسازید.

بذارید در عمل با یک مثال ساده تمرین کنیم.

<?php
/** اینجا حتما باید دوتا ستاره باشه
 * در اینجا توضیحات مربوط به فانکشن زیر رو قرار میدیم
 * اسم کل این قسمت داک بلاک هست
 */
function myFunction( $arr ) {
    // اینجا یک سری کار باحال انجام میدیم
}

به هر یک از این کامنت ها که با /** شروع و با */ تموم میشود "DocBlock" میگن که در مثال بالا مشاهده میکنید.

مزیت های phpdoc

• افزایش خوانایی و قابل فهم کردن کد ها برای برنامه نویس های دیگر
• قابلیت ساختن مستندات به صورت اتوماتیک برای پروژه
• هوشمند تر کردن ادیتور برای فهمیدن عملکرد هر متد یا متغیر

تگ ها

در هر داک بلاک میتونیم از تگ های پیشفرضی استفاده کنیم. این تگ ها به صورت قراردادی در اکثر IDE ها قابل استفاده هست و ادیتور ها برای فهمیدن کارکرد و ویژگی های یک متد یا متغیر از این تگ ها استفاده میکنن.

نحوه درست وارد کردن یک تگ در داک بلاک به صورت زیر هست.

@tagName tag_value

در مثال بالا مقدار tagName به معنی نام تگ و مقدار tag_value به معنی محتوای تگ هستش که بسته به نوع تگ محتوای خاصی و متفاوتی دریافت میکنه.

بعضی از تگ های پرکاربرد

@return

با این تگ اعلام میکنیم که فاکنشن یا متد مورد نظر چه مقداری رو برمیگردونه. برای گفتن اینکه مقداری که برمیگرده از چه نوعی هستش در قسمت اول وارد میکنیم، به جای مقدار {type} مقدار مورد نظر خودمون رو قرار میدیم، مثلا string, int, array و ...

در قسمت بعدی هم متن توضیح درباره چیزی که برمیگردونیم وارد میکنیم به جای {description}

نکته:‌ در مقدار type میتونیم از یک کلاس هم استفاده کنیم.

/**
  * @return {type} {description}
  */

@param

با این تگ اعلام میکنیم که فاکنشن یا متد مورد نظر چه پارامتر هایی داره. در ازای هر پارامتر یک تگ param قرار میدیم. به جای {type} نوع پارامتر رو مشخص میکنیم مثلا string, int. به جای {name} نام پارامتر رو مشخص میکنیم مثلا $name. به جای {description} هم توضیحات مربوط به پارامتر رو قرار میدیم.

در قسمت بعدی هم متن توضیح درباره چیزی که برمیگردونیم وارد میکنیم به جای {description}

نکته:‌ در مقدار type میتونیم از یک کلاس هم استفاده کنیم.

/**
  * @param {type} {name} {description}
  */

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

/**
  * Counts the number of items in the provided array.
  *
  * @param mixed[] $items Array structure to count the elements of.
  *
  * @return int Returns the number of elements.
  */
function count(array $items)
{
  // Some code here...
}

در مثال بالا ما یک فانکشن با نام count داریم که کار اون شمردن تعداد اعضای یک آرایه هستش. در قسمت اول داک بلاک یک متن توضیح برای اینکه این فانکشن چکار میکنه قرار دادیم. در قسمت دوم پارامتر هایی که دریافت میکنه رو قرار دادیم که پارارمتر $items هستش. و در قسمت سوم خروجی فانکشن رو قرار دادیم که یک عدد با فرمت int هستش که تعداد اعضای داخل آرایه میشه.

این هم از قسمت اول. در قسمت های بعدی درباره تگ های دیگر و نحوه ساخت مستندات ادامه میدیم.

تا درودی دیگر بدرود :)