تگ های phpdoc

همانطور که قبلا گفتیم وقتی در یک تیم قرار دارید که کارشان کدنویسی، برنامه نویسی یا توسعه است .زمانی که می‌خواهیم کدها را برای افراد تیم بفرستیم ممکن است با دیدن کدهای ماگیج شوند و یا در تجزیه و تحلیل آن با مشکل روبه رو شوند. یکی از بهترین راه ها مستندسازی است که استفاده phpdoc  راحت تر وبهترمی‌کند.

برای اینکه  با تگ های phpDoc آشنا شوید بهتر است اول با phpdoc آشنا شوید. اگر این چنین است توصیه می کنم مطلب  http://mahdieharghavani.blog.ir/1398/08/15/%D8%A2%D8%B4%D9%86%D8%A7%DB%8C%DB%8C-%D8%A8%D8%A7-phpdocرا بخوانید

 

Phpdoc دارای الگویی خاص است. در این الگو تگ هایی وجود دارد که درباره این تگ ها صحبت می کنیم.

تگ @author

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

این تگ به صورت زیر نوشته می شود.

@author [name] [<email address>]

حال مثالی از این تگ می آوریم.فرض کنید یک فایلphp  را نوشته اید. در بالای فایل مورد نظر می توان کامنت زیر را نوشت.

/**

* @author My_Name

*/

یا به صورت زیر:

/**

* @author My_Name < [e-mail]>

*/

تگ @example

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

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

این تگ به صورت زیر نوشته شده است.

@example [location] [<start-line> [<number-of-lines>] ] [<description>]

یا به صورت زیر:

{@example [location] [<start-line> [<number-of-lines>] ]

[<description>]}

مثال

/**
 * @example location.php my location
 */

تگ@var

 این تگ برای مستندسازی فیلدهای کلاس و متغیرها استفاده می‌شود.

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

این تگ به صورت زیر نوشته شده است.

@var [“Type”] [$element_name] [<description>]

مثال:

/** @var string $name name for student*/
$ name="mahdieh";

تگ@api

با استفاده از این تگ می‌توان مشخص کرد  عنصر برای استفاده سوم شخص مناسب می باشد .

این تگ به صورت زیر نوشته شده است.

@api

مثال:

/**

  * @api

  */

  function ShowText()

  {

    کدها       

  }

تگ @internal

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

این تگ  به صورت زیر نوشته میشود:

@internal [description]

یا  inline:

{@internal [description]}}

مثال:

/**

 * @internal

* {@internal }}

  */

تگ @copyright

با استفاده از این تگ می‌توان درباره copyright عنصر موردنظر می توان اطلاعاتی را مشخص کرد.

این تگ به صورت زیر نوشته می‌شود:

@copyright description

مثال:

/**

  * @copyright The PHPDOCUMENT File

  */

تگ @deprecated

این تگ برای عنصر مرتبطی که منقضی شده و در ورژن‌های آینده حذف می‌شود استفاده می‌شود.

این تگ به صورت زیر نوشته می‌شود:

@deprecated [<version>] [<description>]

مثال:

/**

  * @deprecated

  * @deprecated 2.1.3

  */

 

تگ @filesource

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

این تگ به صورت زیر نوشته می‌شود:

@filesource

مثال:

/**

  * @filesource

  */

تگ @global

این تگ نشان‌دهنده مستندات یک متغییر سراسری یا کاربرد آن است.

این تگ به صورت زیر نوشته می‌شود:

@global [Type] [name] @global [Type] [description]

تگ @ignore

با استفاده از این تگ به PhpDocumentor می‌توان گفت که عنصر مرتبط در مستندات درج نشده است.

این تگ به صورت زیر نوشته می‌شود:

@ignore [<description>]

مثال:

/**

      * @ignore

   */

تگ @internal

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

این تگ به صورت زیر نوشته می‌شود:

@internal [description]

یا

{@internal [description]}}

مثال:

/**

  * @internal 

  * {@internal }

  */

 

تگ @license

این تگ مشخص می‌کند که کد مرتبط با آن، تحت چه لایسنسی نوشته شده است.

این تگ به صورت زیر نوشته می‌شود:

@license [<url>] [name]

مثال:

/**

  * @license ta

  * @license http://licence.com/ta ta

  */

تگ @link

این تگ ارتباط بین صفحه‌ای از یک وب سایت و عنصر مرتبط را نشان می‌دهد.

این تگ  به صورت زیر نوشته میشود:

@link [ URI] [<description>]

یا

{@link [URI] [<description>]}

مثال

/**

  * @link http://example.com/myLink

  */

 @method تگ

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

این تگ به صورت زیر نوشته می‌شود:

@method [[static] return type] [name]([[type] [parameter]<, ...>]) [<description>]

مثال:

/**

  * @method string GetName()

  * @method void setName(string $name)

  * @method SetName(string $string)

  * @method static string staticName()

  */

تگ @package

 این تگ عنصر مرتبط را در یک گروه یا بخش فرعی دسته‌‌بندی می‌کند.

این تگ به صورت زیر نوشته می‌شود:

@package [level 1]\[level 2]\[etc.]

مثال:

/**

  * @package PSR\Documentation\API

  */

تگ @param

این تگ برای مستندسازی آرگومان‌های متد یا تابع استفاده می‌شود.

این تگ به صورت زیر نوشته می‌شود:

@param [Type] [name] [<description>]

مثال:

/**

  * @ param float $age student

  */

تگ @property

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

این تگ به صورت زیر نوشته می‌شود:

@property [Type] [name] [<description>]

مثال:

/**

  * @property string $My_Property

  */

تگ @property-read

با استفاده از این تگ می‌توان به کلاس اجازه داد تا بداند که در آن کدام فیلدهای جادویی که فقط خواندنی هستند، استفاده شده‌اند.

این تگ به صورت زیر نوشته می‌شود:

@property-read [Type] [name] [<description>]

مثال:

/**

  * @property-read string $My_Property

  */

تگ @property-write

با استفاده از این تگ می‌توان به کلاس اجازه داد تا بداند که در آن کدام فیلدهای جادویی که فقط نوشتنی هستند، استفاده شده‌اند.

این تگ به صورت زیر نوشته می‌شود:

@property-write [Type] [name] [<description>]

مثال:

/**

  * @property-write string $My_Property

  */

تگ @return

این تگ برای مستندسازی مقدار بازگشتی متد یا تابع، استفاده می‌شود.

این تگ به صورت زیر نوشته می‌شود:

@return [Type] [<description>]

مثال:

/**

  * @return integer

  */

تگ @see

این تگ، یک ارجاع از عنصر مرتبط به عناصر دیگر یا یک وب سایت را نشان می‌دهد.

این تگ به صورت زیر نوشته می‌شود:

@see [URI | FQSEN] [<description>]

یا

{@see [URI | FQSEN] [<description>]}

/**

  * @see http://example.com/Mu_Example

  * @see MyClass::$items

  */

تگ @since

با استفاده از این تگ می‌توان نشان داد که عنصر مرتبط از چه ورژنی از برنامه به بعد در دسترس بوده است.

این تگ به صورت زیر نوشته می‌شود:

@since [version] [<description>]

مثال:

/**

  * @since 2.0.1 Added the $Since

  * @since 1.0.2 Added the $ Since

  * @since 3.0.0

  */

 تگ @source

این تگ برای نشان دادن سورس کد عنصر مرتبط است.

این تگ به صورت زیر نوشته می‌شود:

@source [<start-line> [<number-of-lines>] ] [<description>]

مثال:

/**

  * @source 21  58

  */

تگ @subpackage

این تگ عنصر مرتبط را در یک گروه منطقی یا بخش فرعی دسته‌‌بندی می‌کند.

این تگ به صورت زیر نوشته می‌شود:

@subpackage [name]

مثال:

/**

  * @ subpackage Student

  */

تگ @throws

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

این تگ به صورت زیر نوشته می‌شود:

@throws [Type] [<description>]

مثال:

/**

  * @throws InvalidArgumentException if the provided argument is not of type

  */

تگ @todo

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

این تگ به صورت زیر نوشته می‌شود:

@todo [description]

مثال:

/**

  * @todo add student

  */

 

تگ @uses

این تگ یک ارجاع از یک عنصر تنها را نشان می‌دهد.

این تگ به صورت زیر نوشته می‌شود:

@uses [FQSEN] [<description>]

مثال:

/**

  * @uses MyClass::$uses

 */

تگ @version

این تگ برای نشان دادن ورژن فعلی عناصر ساختاری است.

این تگ به صورت زیر نوشته می‌شود:

@version [<vector>] [<description>]

مثال:

/**

  * @version 2.1.3

  */