آموزش PHPDoc و کامنت گذاری در وردپرس

در این فیلم آموزشی، شما با روش های کامنت گذاری استاندارد با استفاده از PHPDoc آشنا می شوید. این فیلم آموزشی راهنمای جامع مستند سازی کدهای شما توسط اصول PHPDoc می باشد.

در ابتدا شما با اهمیت گذاشتن کامنت در کدهای خود آشنا می شوید و سپس به توضیح بخش های مختلف PHPDoc خواهیم پرداخت.

سپس با اجزا مختلف DocBlock ها و نحوه استفاده درست از آن ها آشنا خواهید شد. بعد از آن به طور کامل شرح می دهیم که چه چیزهایی را می توانیم با DocBlock ها مستند بکنیم.

آموزش مستندسازی با PHPDoc

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

برای آشنایی با استاندارد های کدنویسی در وردپرس (بخش اول)، می توانید از این لینک استفاده کنید.

در هنگام کار با CodeSniffer مشاهده کردیم که بسیاری از Warning ها مربوط به نداشتن DocBlock ها و مستند نکردن بخش های مختلف کد بود. به دلیل اینکه توضیح این مطلب، طولانی بود، تصمیم گرفتیم تا در بخش دوم، به آموزش کامل آن بپردازیم.

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

پس از یادگیری بخش های مختلف PHPDoc و آشنایی با اجزا یک DocBlock، به تشریح کلیه تگ ها خواهیم پرداخت. در انتها نیز به صورت عملی بخش هایی از یک کد پلاگین وردپرس را کامنت گذاری خواهیم کرد.

در آموزش تصویری راهنمای جامع PHPDoc ، با چه مواردی آشنا خواهید شد؟

فیم آموزش PHPDoc ،  در مدت زمان تقریبی 44 دقیقه برای شما دوست عزیز و به صورت تصویری تهیه شده است.

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

  • اهمیت استفاده از کامنت گذاری در کدهای برنامه

  • معرفی اولیه PHPDoc  و آشنایی با سبک به کار رفته در PHPDoc

  • کاربردهای اساسی PHPDoc (شلیک یک تیر با چند نشان)

  • معرفی phpDocumentor و نحوه استفاده آن از PHPDoc

  • آشنایی با فرمت های تولید شده یک مستند توسط phpDocumentor و آشنایی با PEAR در PHP

  • آشنایی با اجزا PHPDoc یا همان DocBlock ها

  • معرفی اجزا اصلی یک DocBlock شامل Short Description (یا  Summery)، بخش Long Description (یا Description) و بخش تگ ها یا Tags

  • قواعد نامگذاری در PHPDoc ، معرفی package ها و نکات مرتبط با آن

نکته: در صورتی که با شی گرایی و کاربرد کلاس های در PHP، آشنایی ندارید و یا با انواع متغیر در آن آشنا نیستید، مقاله های زیر به صورت کامل این موارد را شرح داد اند:

آموزش پیشرفته شی گرایی در PHP
آشنایی با انواع متغیرها در PHP
  • آشنایی با package ها و همین طور subpackage ها در PHPDoc، آشنایی با پکیج default

  • معرفی level های مختلف DockBlock شامل file-level و class-level و page-level

  • نحوه مستند سازی محتوای یک فایل ای استفاده از PHPDoc file header block

  • نحوه مستندسازی برای دستورات require و include به صورت Inline

  • آشنایی با نحوه کامنت گذاری برای تعریف کلاس ها، تابع ها و متدهای داخل یک کلاس

  • آشنایی با مهم ترین تگ های مورد استفاده در یک کلاس مثل snice و see و link

  • آشنایی با پر کاربردترین تگ های در تعریف تابع ها و متد ها مثل param و return و global

  • آشنایی با قواعد نوشتن در تگ ها یا رعایت Syntax های مرتبط با هر تگ، بررسی syntax های تگ های var و param و global

  • نحوه کامنت گذاری برای تعریف خاصیت ها (Class Property) و متغیرها با PHPDoc

  • نحوه کامنت گذاری برای تعریف ثابت ها در بین کدهای برنامه

اگر با انواع ثابت ها در PHP آشنایی ندارید، می توانید از این لینک استفاده کنید.
  • آشنایی با PSR ها در زبان PHP

  • بررسی عملی نحوه کامنت گذاری و برطرف کردن مشکلات آن در یک پلاگین وردپرس

  • انجام عملی کامنت گذاری header یک پلاگین برای وردپرس

  • آشنایی با تگ wordpress-plugin در هدر یک پلاگین وردپرس

  • تصحیح کامنت گذاری برای تعریف ثابت در پلاگین وردپرس

  • گذاشتن DocBlock برای تعریف یک کلاس در پلاگین

  • استفاده از DocBlock برای تعریف یک Property در داخل یک کلاس در پلاگین وردپرسی

  • استفاده از کامنت برای تشریح کاربرد تعریف ثابت ها در بین کدهای یک پلاگین

  • مثال کاربردی از کامنت گذاری برای تابع register_activation_hook

  • مثال عملی برای نحوه مستند سازی متدها با استفاده از بلاک های مستندسازی در یک کلاس

  • اجرای عملی کلیه موارد فوق بر روی کلاس، در داخل یک افزونه وردپرس، با استفاده از PHP_CodeSniffer و همین طور PhpStorm

نمونه یک 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” اضافه کنیم. در ضمن اگر این مقاله را مفید دیدید، حتما آن را به دوستان خود معرفی کرده یا در شبکه های اجتماعی به اشتراک بگذارید.

نظر شما در درباره این مقاله چیست؟

راهنما برای مطالعه بیشتر:

برای تولید فیلم آموزش بک آپ وردپرس ، از لینک های زیر استفاده شده است که برای مراجعه به آن ها می توانید از لیست زیر استفاده کنید:

راهنما برای خواندن سایر مقالات سایت به صورت دسته بندی شده:

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

بازگشت به وبلاگ وبمستر وردپرس