کامنت‌های PHPDoc با دو ستاره (/) آغاز می‌شوند و می‌توانند شامل تگ‌های مختلفی باشند که اطلاعات مهمی را در مورد توابع، کلاس‌ها، ویژگی‌ها و غیره ارائه می‌دهند. درمورد این تگ ها به طور کامل توضیح داده می شود.
نمونه کد:
/**
* Calculate the sum of two numbers.
*
* @param int $a first number
* @param int $b second number
* @return int The sum of two numbers
*/
function add($a, $b) {
return $a + $b;
}
کد بالا پارامتر ها و خروجی تابع را توضیح می دهد.
از آنجایی که PHPDoc ها کامنت هستند توسط PHP تفسیر نمی شوند به همین دلیل در زمان اجرا در دسترس نیستند و برای خواندن آنها باید از ابزار هایی مانند PHPDocumentor استفاده کنید، ولی IDE ها توان تفسیر آنها را دارا می باشند و اگر کتابخانه ای توسعه می دهید به استفاده کننده گان کمک می کنند.
بررسی تگ ها:
تگ های PHPDoc با @ شرع می شوند.
@api
نشان دهنده آن دسته از عناصر API است که عمومی تلقی می‌شوند.
class UserService
{
/**
* @api
*/
public function getUser() {}
/**
* This method is "package scope", not public-API.
*/
public function callMefromAnotherClass() {}
}
در مثال بالا متد GetUser به عنوان متد عمومی درون api مشخص شده در صورتی که متد دوم مربوط به api عمومی نیست.
———
@author [name] [<email address>]
مشخص کننده نویسنده کد.
/**
* @author John Doe <john@gmail.com>
*/
———
@category [description]
دسته‌بندی کلی کلاس یا توابع را مشخص می‌کند.
/**
* @category MyCategory
*/
———
@copyright [description]
متن حق کپی‌رایت را برای کد مشخص می‌کند.
/**
* @copyright Copyright 1994-2024 Acme Corporation
*/
———
@deprecated [<Semantic Version>] [<description>]
این تگ نشان می‌دهد که یک تابع یا کلاس دیگر استفاده نمی‌شود و ممکن است در نسخه‌های آینده حذف شود.
/**
* @deprecated 2.0 Use newFunction() instead.
*/
function oldFunction() {
}
———
@example [location] [<start-line> [<number-of-lines>] ] [<description>]
یک فایل نمونه که نحوه استفاده از کد را نشان می‌دهد.
/**
* @example /path/to/example.php
*/
———
@filesource
نشان می‌دهد که متن کامل فایل باید در مستندات نمایش داده شود.
<?php
/**
* @filesource
*/
———
@global [Type] [name]
@global [Type] [description]
توضیح می‌دهد که یک تابع به یک متغیر جهانی دسترسی دارد.
/**
* @global int $GLOBAL_VAR Description of global variable.
*/
function useGlobal() {
global $GLOBAL_VAR;
}
———
@ignore [<description>]
باعث می‌شود که ابزار مستندسازی یک عنصر خاص را نادیده بگیرد.
/**
* @ignore
*/
define("RUNTIME_OS","Windows");
———
@internal [description]
اطلاعاتی که فقط برای توسعه‌دهندگان داخلی استفاده می‌شود.
/**
* @internal This is only for advanced developers.
*/
function count() {}
———
@license [<url>] [name]
نوع لایسنس کد را مشخص می‌کند.
/**
* @license GPL
* OR
* @license https://opensource.org/licenses/gpl-license.php GNU Public License
*/
———
@link [URI] [<description>]
لینک به منبع مرتبط.
/**
* @link https://example.com More information here
*/
———
@method [[static] return type] [name]([[type] [parameter]<, ...>]) [<description>]
توصیف متد مجازی در کلاس، مفید برای کلاس‌هایی با متدهایی که با مجیک متد (__call) تعریف شده‌اند.
/**
* @method int magicMethod(string $param) Description
*/
class MyClass {}
———
@package [level 1]\\[level 2]\\[etc.]
تعریف بسته‌ای که کلاس یا تابع مرتبط با آن است.
/**
* @package Core
*/
———
@param [<Type>] [name] [<description>]
توصیف پارامترهای یک تابع.
/**
* @param int $a First number
* @param int $b Second number
*/
function add($a, $b) {
return $a + $b;
}
ادامه تگ ها در پست بعدی توضیح داده می شود.
👤 AmirHossein
💎 Channel: @DevelopixPHP