معرفی

هدف اصلی این PSR ارائه یک تعریف کامل و رسمی از استاندارد PHPDoc است.

  • “PHPDoc” بخشی از مستنداتی است که اطلاعاتی از جنبه “مولفه ساختاری”(structural element) فراهم می کند. لازم به دقت است که PHPDoc و DocBlock دو مولفه جداگانه هستند. DocBlock ترکیبی از DocComment است که یک نوع از comment و مولفه PHPDoc است.
  • “Element Structural” مجموعه ای از ساختارهای برنامه نویسی است که ممکن است توسط DocBlock پیش برود. این مجموعه شامل ساختارهای زیر است:
  1. file
  2. require(_once)
  3. include(_once)
  4. class
  5. interface
  6. trait
  7. function (including methods)
  8. property
  9. constant
  10. variables, both local and global scope.

مثال:

یا

یک نمونه کاربردی که فراتر از محدوده این استاندارد می آید این است که متغیر را به صورت ضمنی وارد کنید. چندین IDE از این اطلاعات برای کمک به قابلیت تکمیل خودکار( auto-completion) استفاده می کنند.

  • “DocComment” یک نوع خاص از comment است که باید :
  1. با کاراکتر **/ که بوسیله کاراکتر فضای خالی ادامه پیدا میکند شروع شود.
  2. با کاراکتر /* خاتمه یابد.
  3. خطوط زیاد و یا هیچ خطی بین آنها نباشد.

در صورتی که طول  DocComment چند خط باشد، هر خط باید با ستاره (*) آغاز شود.

مثال تک خطی :

مثال چند خطی :

  • “DocBlock” یک “DocComment” است که شامل یک ساختار “PHPDoc” است و نشان دهنده نمایش in-source پایه است.
  • “Tag” یک جز واحد از اطلاعات متا در مورد “مولفهساختاری” یا یک جزء آن است.
  • “Inline PHPDoc” یک “PHPDoc” مرتبط با “Tag” بجای “مولفه ساختاری” است. “Inline PHPDoc”  توصیف قسمتی از “Tag” را جایگزین می کند.
  • “Type” مشخص کننده این است که چه نوع داده ای با یک مولفه ترکیب شود.برای تعیین مقادیر دقیق آرگومان، ثابت ها، ویژگی ها و موارد دیگر استفاده می شود.
  • “FQSEN” یک نام اختصاری برای نام عناصر ساختاری کامل است.این نشانه در نام کلاس کامل  گسترش می یابد و نشانه های برای مشخص کردن اعضاء class/interface/trait اضافه می کند و اصول FQCN را به واسط های کاربری، صفات، توابع و ثابت های سراسری دوباره اعمال می کند.

علامت های زیر  در هر نوع از “عناصر ساختاری” می تواند استفاده شود:

Namespace\My\Space Function\My\Space\myFunction() Constant\My\Space\MY_CONSTANT Class\My\Space\MyClassInterface\My\Space\MyInterface Trait\My\Space\MyTrait Method\My\Space\MyClass::myMethod() Property:\My\Space\MyClass::$my_property Class Constant\My\Space\MyClass::MY_CONSTANT

FQSEN دارای تعریف ABNF  زیر است:

FQSEN = fqnn / fqcn / constant / method / property / function
( [ fqnn = "\" [name] *("\" [name
fqcn = fqnn "\" name
constant = (fqnn "\" / fqcn "::") name
"()" method = fqcn "::" name
property = fqcn "::$" name
"()" function = fqnn "\" name
( "_" /name = (ALPHA / "_") *(ALPHA / DIGIT

اصول پایه :

  • PHPDoc همیشه باید در “DocComment” موجود باشد ترکیبی از این دو “DocBlock” نامیده می شود.
  • DocBlock مستقیما یک “عنصر ساختاری” را پیش میبرد.

استثناء این اصل در سطح فایل DocBlock است که باید در بالای یک فایل کد PHP source بعنوان اولین DocBlock در یک فایل قرار داده شود.
مثالی از سطح فایل DocBlock :

فرمت PHPDoc
فرمت PHPDoc تعریف ABNF زیر را دارد:

خلاصه فرمت PHPDoc:

خلاصه باید شامل انتزاعی از “مولفه ساختاری” باشد که اهداف را تعریف می کند. توصیه می شود شرح خلاصه ها یک خط یا حداکثر دو خط، و نه بیشتر باشد.
خلاصه می تواند به هر دوشکل زیر پایان یابد:

  1. یک توقف کامل (.) که بدنبال یک line break می آید.
  2. دو line breaks متوالی

اگر توصیفی ارائه شود، باید با یک خلاصه پیش برده شود.در غیر این صورت توصیف بعنوان خلاصه در نظر گرفته خواهد شد،تا زمانیکه پایان خلاصه برسد.
از آنجاییکه خلاصه قابل مقایسه با عنوان فصل است استفاده از فرمت کوتاه مفید است.

توصیف

وجود داشتن “توصیف” اختیاری است. اما زمانیکه “مولفه ساختاری” شامل operationهای زیاد یا operation های پیچیده است، اجباری می شود.
استفاده های متداول برای توصیف (در میان دیگران) عبارتند از:
فراهم کردن جزئیات بیشتر نسبت به خلاصه در مورد اینکه این متد چه کاری انجام می دهد.تعیین اینکه چه مولفه های childی یک آرایه ورودی یا خروجی، یا یک شیء ، است.

Inline PHPDoc

ممکن است تگ های ویژه ای، قسمت “Inline PHPDoc” را در انتهای تعریف “Tag” خود داشته باشند. “Inline PHPDoc” یک مولفه “PHPDoc” است که در بین پرانتزهای بسته قرار دارد که تنها در انتهای “Tag” متوالی قرار می گیرد.عنصر “Inline PHPDoc” باید هر توضیحی را که ممکن است ارائه شود جایگزین کند.یک مثال تگ method @ است.

مثال:

ارث بری
یک PHPDoc که با یک “مولفه ساختاری” مرتبط شده است که مولفه ساختاری را پیاده سازی، گسترش یا لغو می کند، توانایی ارث بری بخشی از اطلاعات از PHPDoc مرتبط با «مولفه ساختاری» که پیاده سازی، گسترش یا لغو شده است را دارد.PHPDoc برای هر نوع از “مولفه ساختاری” باید اجزای زیر را به ارث برده باشد:

  • خلاصه
  • توصیف و
  • زیرمجوعه مشخصی از “Tag”ها
  1. @version
  2. @author
  3. @copyright

همچنین PHPDoc برای هر نوع «مولفه ساختاری» باید یک زیر مجموعه مشخص از Tagها را براساس اینکه با کدام «مولفه ساختاری» مرتبط شده است را به ارث ببرد. اگر یک PHPDoc یک قسمت از جمله خلاصه یا توصیفات را نداشته باشد، آن بخش همواره به طور ضمنی به ارث برده می شود. در ادامه لیستی از مولفه هایی که DocBlocks قادر به ارث بری اطلاعات از super-element’s DocBlock است آورده شده است:

  • یک کلاس یا واسط کاربری DocBlock می تواند اطلاعات را از یک کلاس یا واسط کاربری که گسترش یافته است، ارث ببرد.
  • یک ویژگی  DocBlock می تواند اطلاعات را از یک ویژگی با نام یکسان که در یک superclass مشخص شده است، ارث ببرد.
  • یک روش DocBlock می تواند اطلاعات را از یک روش با نام یکسان که در یک superclass مشخص شده است، ارث ببرد.
  • یک روش DocBlock می تواند اطلاعات را از یک روش با نام یکسان که در یک واسط کاربری پیاده سازی شده است، ارث ببرد.

منبع : https://github.com

PSR-5 : PHPDoc

دیدگاهتان را بنویسید

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