آموزش PHPDoc و کامنت گذاری در وردپرس
در این فیلم آموزشی، شما با روش های کامنت گذاری استاندارد با استفاده از PHPDoc آشنا می شوید. این فیلم آموزشی راهنمای جامع مستند سازی کدهای شما توسط اصول PHPDoc می باشد.
در ابتدا شما با اهمیت گذاشتن کامنت در کدهای خود آشنا می شوید و سپس به توضیح بخش های مختلف PHPDoc خواهیم پرداخت.
سپس با اجزا مختلف DocBlock ها و نحوه استفاده درست از آن ها آشنا خواهید شد. بعد از آن به طور کامل شرح می دهیم که چه چیزهایی را می توانیم با DocBlock ها مستند بکنیم.
این آموزش، از سری سه قسمتی مربوط به آموزش استانداردهای کدنویسی در وردپرس می باشد. در بخش اول در مورد استانداردهای کدنویسی در وردپرس صحبت کردیم.
در هنگام کار با CodeSniffer مشاهده کردیم که بسیاری از Warning ها مربوط به نداشتن DocBlock ها و مستند نکردن بخش های مختلف کد بود. به دلیل اینکه توضیح این مطلب، طولانی بود، تصمیم گرفتیم تا در بخش دوم، به آموزش کامل آن بپردازیم.
در این فیلم آموزشی، به طور جامع به بررسی PHPDoc و ساختار آن می پردازیم. شما با جز به جز این سیتستم و نحوه کامنت گذاری در PHP و همین طور وردپرس آشنا خواهید شد.
پس از یادگیری بخش های مختلف PHPDoc و آشنایی با اجزا یک DocBlock، به تشریح کلیه تگ ها خواهیم پرداخت. در انتها نیز به صورت عملی بخش هایی از یک کد پلاگین وردپرس را کامنت گذاری خواهیم کرد.
در آموزش تصویری راهنمای جامع PHPDoc ، با چه مواردی آشنا خواهید شد؟
فیم آموزش PHPDoc ، در مدت زمان تقریبی ۴۴ دقیقه برای شما دوست عزیز و به صورت تصویری تهیه شده است.
در این فیلم آموزشی، به صورت کامل به موارد زیر پرداخته شده است که لیست آن به شرح زیر می باشد:
چه چیزهایی را می توانیم با DocBlock ها مستند بکنیم؟
در نظر داشته باشید که می توانیم فایل ها، کلاس ها، تابع ها یا متدها، خاصیت های یک کلاس، متغیرهای سراسری، متغیرها، دستورهای حاوی include و require و همچنین ثابت ها را، با استفاده از DocBlock ها مستند سازیم. در نظر داشته باشید که رابط ها و triat ها هم به مانند کلاس قابل مستندسازی می باشد.
نکته: در صورتی که با شی گرایی و کاربرد کلاس های در PHP، آشنایی ندارید و یا با انواع متغیر در آن آشنا نیستید، مقاله های زیر به صورت کامل این موارد را شرح داد اند:
نمونه یک DocBlock با استفاده از تگ های کاربردی آن
شما در این بخش می توانید نمونه ای از یک 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 Mehdi Soltani <soltani.n.mehdi@gmail.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 sample_function()
{
// ...
}
لیست تگ های مورد استفاده در DocBlock
شما در این بخش می توانید به لیست تگ های مورد استفاده در DocBlock و اینکه در چه بخش های مستند سازی می توانیم از آن استفاده کنیم را، به صورت خلاصه در جدول زیر مشاهده فرمایید:
| نام تگ | جایی که می تواند استفاده شود | توضیح کوتاه در مورد نحوه استفاده از تگ در این بخش |
|---|---|---|
| api | متدها | مشخص کردن برای استفاده third-party |
| author | در همه بخش ها | مشخص کردن نویسنده |
| copyright | در همه بخش ها | نمایش اطلاعات مرتبط با کپی رایت |
| deprecated | در همه بخش ها | نمایش عناصر deprecate شده و حذف شده |
| example | در همه بخش ها | نمایش یک بخش به عنوان مثال |
| filesource | در همه بخش ها | نمایش سورس فایل جاری برای استفاده در خروجی |
| global | برای متغیر و تابع | نمایش مشخصات یک متغیر سراسری |
| ignore | در همه بخش ها | در نظر گرفته نشدن برای تولید مستند توسط PhpDocumentor |
| internal | در همه بخش ها | مشخص کردن عناصر داخلی |
| licence | در فایل و کلاس | مشخص کردن لایسنس مرتبط با آن |
| link | در همه بخش ها | لینک مرتبط با آن بخش |
| method | در کلاس | مشخص کردن متدهای یک کلاس |
| package | در کلاس و فایل | برای دسته بندی فایل ها و کلاس ها |
| param | در تابع و متد | مشخص کردن آرگومان های ورودی یک تابع یا یک متد |
| property | در کلاس | مشخص کردن فیلد های مورد استفاده در یک کلاس |
| property-read | در کلاس | مشخص کردن فیلدهای فقط خواندنی در یک کلاس |
| property-write | در کلاس | مشخص کردن فیلدهای فقط نوشتنی در یک کلاس |
| return | در تابع و متد | مشخص کردن مقدار خروجی یک تابع یا متد |
| see | در همه بخش ها | لینک به توضیحات اضافه تر یا موارد وابستگی آن بخش به سایر دیگر |
| source | در همه بخش ها به جز فایل | نمایش سورس مرتبط با آن بخش |
| subpackage | در فایل و کلاس | برای ایجاد دسته بندی های تو در تو برای پیکیج ها |
| throws | در فایل و کلاس | مشخص کردن خطای مرتبط با آن فایل یا کلاس |
| todo | در همه بخش ها | مشخص کردن بخش های در حال توسعه در آینده که هنوز تمام نشده |
| uses | در همه بخش ها | مشخص کردن نحوه استفاده از یک عنصر دیگر |
| var | در خاصیت های کلاس | مشخص کردن خاصیت های یک کلاس |
| version | در همه بخش ها | مشخص کردن ورژن فعلی آن بخش |
نتیجه گیری برای آموزش PHPDoc و استاندارد های کامنت گذاری
در این آموزش تصویری رایگان، در ابتدا در مورد اهمیت کامنت گذاری استاندارد، در یک برنامه صحبت شد. سپس به صورت کامل در مورد PHPDoc توضیح داده شد.
در ادامه با phpDocumentor و همین طور ساختار PHPDoc به صورت کامل آشنا گشتیم. سپس با DocBlock ها و اجزا آن آشنا شده و بسیاری از تگ های کاربردی آن را مورد بررسی قرار دادیم.
در انتها نیز با یک مثال عملی، به صورت کاربردی بر روی چند فایل یک پلاگین وردپرسی، کامنت گذاری استاندارد را انجام دادیم.
ممکن است شما با موارد بیشتری در این حوزه آشنا باشید، که ما فراموش کرده ایم تا آن ها را در این مقاله قرار دهیم.
اگر شما از این موارد آگاه هستید، حتما در بخش نظرات عنوان کنید تا آن را به مقاله “آموزش PHPDoc” اضافه کنیم. در ضمن اگر این مقاله را مفید دیدید، حتما آن را به دوستان خود معرفی کرده یا در شبکه های اجتماعی به اشتراک بگذارید.
راهنما برای مطالعه بیشتر:
برای تولید فیلم آموزش بک آپ وردپرس ، از لینک های زیر استفاده شده است که برای مراجعه به آن ها می توانید از لیست زیر استفاده کنید:
راهنما برای خواندن سایر مقالات سایت به صورت دسته بندی شده:
شما می توانید از طریق لینک های کاربردی زیر به سایر مقالات سایت که کاملا بصورت طبقه بندی شده وجود دارد، مراجعه نموده و از آن ها استفاده کنید:
ثبت ديدگاه