لوگوی وبسایت
تمام آموزش های وبسایت رایگان می باشد ، پس از صفحات مختلف سایت دیدن فرمایید .

آشنایی و شروع کار با PHPDoc ، کامنت هایی مهم تر از نان شب

سلام دوستان . امیدوارم خسته نباشید . در این آموزش قرار است با PHPDoc به عنوان مغز تجزیه تحلیل IDE های PHP آشنا شویم .

چرا باید از کامنت های PHPDoc استفاده کنیم ؟

برای مثال ابتدا فرض کنید از PHPStorm به عنوان IDE استفاده میکنیم.

کد زیر را در یک فایل .php که درون PHPStorm ساخته اید ، قرار دهید :

همانطور که میدانیم PHPStorm هوشمند ترین IDE برای PHP هست . اما … . زمانی که می خواهیم برای مثال $instance->get('key1') را اجرا کنیم ، IDE نمی تواند متوجه متد get() در این شی ما شود . علت چیست ؟

تنها علت این است که ما طوری شی را ساخته این و برگرداندیم که IDE توانایی فهم آن را ندارد .

تابع get_called_class() نام کلاسی را که ما صدا زده ایم بر میگرداند که نام کلاس ما Child هست و ما یک Instance با توجه به مقدایر داده شده از کلاس ساخته و بر می گردانیم .

حالا فرض کنید شما سازنده ی فریم ورک Yii2 بودید ! این روش در این فریم ورک به مراتب تکرار شده است اما چطور PHPStorm تک تک متد های تک تک دریافتی ها را می شناسد ؟ چون از PHPDoc استفاده شده است .

PHPDoc به عنوان یک SDK در اکثر IDE های بزرگ وجود دارد و ما میتوانیم از آن استفاده کنیم .

برای مثال کد بالا را به شکل زیر تغییر دهید :

اگر امتجان کنید می بینید که $instance تمام مقادیر مد نظر ما را دارد ! می دانید این یعنی چه ؟ تا به حال فکر می کردیم کامنت ها برای راحتی فهم انسان هاست اما این کامنت های بخصوص برای راحتی فهم ماشین هست !

آشنایی با اصول کامنت ها در PHPDoc

در PHPDoc ما طبق اصولی که هست ، تعریف هایمان را بین کامنت ایی به شکل زیر قرار میدهیم :

توجه کنید که آغاز کامنت ۲ عدد * داریم .

حالا میتوانیم با استفاده از تگ ها به تعریف بخش های مختلف کد هایمان بپردازیم . این تگ ها بیشتر در شی گرایی به کار میروند .

تعریف متغیر با استفاده از تگ @var

فرض کنید قرار است یک فایل مانند part.php را در فایل base.php اینکلود کنید ، در فایل base.php اطلاعات زیر را وارد کنید :

 

حالا در فایل site.php ما به $config دسترسی داریم . باز هم با این حال PHPStorm متوجه این موضوع می شود اما در آموزش های آینده که سر کار ما با کلاس های بسیار هست ، PHPStorm هم کم میاورد .

برای چنین مواردی در part.php از @var استفاده میکنیم .

کد زیر را در part.php قرار دهید :

تعریف تگ @var : 

اگر از تگ @var در یک فایل استفاده نماییم . باید بعد از @var ما ۲ عدد عبارت نیز وارد می کنیم . عبارت اول نوع متغیر هست که میتواند نام یک نوع کلاس ، string  int و … باید . عبارت دوم نیز نام متغیر هست .

اگر از تگ @var قبل از یک property در یک کلاس استفاده نماییم . فقط باید نوع اطلاعات درون آن متغیر را وارد نماییم.

بعد از این ورودی ها هر عبارتی وارد کنیم به عنوان توضیحات در نظر گرفته می شود .

تعریف property های کلاس با استفاده از تگ @property

این تگ را باید قبل از تعریف کلاس صدا زد . این تگ بعد از خودش ۲ ورودی میگیرد . ورودی اول نوع property می باشد و ورودی دوم نام آن . هر عبارتی بعد از آن وارد شود ،‌به عنوان توضیحات در نظر می گیرد .

توجه کنید که اگر property ما امکان داشت از انواع مختلفی باشد ، در ورودی اول میتوانیم با استفاده از | انواع مختلفی را وارد نماییم .

تعریف متد های اضافی با استفاده از @method

کد زیر را در نظر بگیرید :

IDE نمی تواند تابع sum را تشخیص دهد پس باید ما در PHPDoc تعریف کنیم .

در تگ @method ابتدا باید نوع خروجی متد ، سپس نام متد با () و سپس نام متد با ورودی های متد را وارد میکنیم .

پس باید کد ما به شکل زیر تغییر کند :

شما می توانستید مثلا از @method int sum() sum($var1,$var2) هم استفاده نمایید . به هر حال تعریف دست شما است .

تعیین نوع خروجی متد با استفاده از @return

ما به این تگ ابتدا باید خروجی های متد را بدهیم که اگر متد چندین نوع خروحی داشت می توانیم از | نیز استفاده کنیم سپس به عنوان ورودی دوم که ضروری هم نیست می توانیم توضیحات را وارد کنیم.

توجه کنید که @return باید قبل از تعریف متد بیاید.

اگر می خواهید همان کلاسی را که به وسیله ی متد تعریف کردید را خروجی بدهید از $this استفاده نمایید.

 

تگ های بسیاری در سایت PHPDoc وجود دارد که میتوانید از آن ها استفاده نمایید .

برای ورود به سایت PHPDoc کلیک نمایید 

ما در این آموزش تگ های بسیار مهم و کاربردی را آموزش دادیم و انشالله در آموزش های بعدی که قرار است وارد بحث پروژه شویم از این تگ ها و تگ های دیگر نیز استفاده خواهیم کرد و با آن ها آشنا خواهیم شد.

بر چسب های پست : , , , , , , ,
مطالب مرتبط
شاید شما هم بخواهید آدرس های خوانا و زیبایی برای سایتتان ایجاد کنید . و قطعا طی ...
۲۳ اردیبهشت ۹۵
4 دیدگاه
سلام دوستان . در قسمت قبلی با کلاس ها ،‌اشیا ، خواص و متد ها آشنا شدیم و در این ...
۰۳ اردیبهشت ۹۵
2 دیدگاه
متاسفانه امروزه برای بیشتر برنامه نویس های PHP مفهوم شی گرایی تبدیل به یک مفهوم ...
۰۲ اردیبهشت ۹۵
1 دیدگاه
3 دیدگاه برای “آشنایی و شروع کار با PHPDoc ، کامنت هایی مهم تر از نان شب”
  1. سلام.وبسایت خیلی خوب و جامعی
    دارید.ممنون

  2. علی کشفی گفت:

    خیلی جالب بود، از این کامنت ها توی لاراول و سورس های گیت هاب زیاد دیده بودم.
    خیلی برام جالب بود کاربردشون رو فهمیدم ممنون، لذت بردیم :))

  3. فرهاد گفت:

    بسیار عالی .منو چند قدم تا یک برنامه نویس حرفه ای شدن کمک کرد.

پاسخ دهید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *

ورود به حساب کاربری
بستن این پنجره