PSR-5 : PHPDoc

مدیر محتوا ژانویه 28, 2018 PHP پیام بگذارید 73 بازدیدها

معرفی

هدف اصلی این 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.

مثال:

/** @var int $int This is a counter. */

$int = 0;

// there should be no docblock here

$int++;

یا

/**

* This class acts as an example on where to position a DocBlock.

*/

class Foo

{

/** @var string|null $title contains a title for the Foo with a max. length of 24 characters */

protected $title = null;

/**

* Sets a single-line title.

*

* @param string $title A text with a maximum of 24 characters.

*

* @return void

*/

public function setTitle($title)

{

// there should be no docblock here

$this->title = $title;

}

}

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

/** @var \Sqlite3 $sqlite */

foreach($connections as $sqlite) {

// there should be no docblock here

$sqlite->open(‘/my/database/path’);

<…>

}

  • “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 :

<?php

/**

* This is a file-level DocBlock

*/

/**

* This is a class DocBlock

*/

class MyClass {

}

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

PHPDoc = [summary] [description] [tags]

inline-phpdoc = “{” *SP PHPDoc *SP “}”

summary = *CHAR (“.” 1*CRLF / 2*CRLF)

description = 1*(CHAR / inline-tag) 1*CRLF ; any amount of characters

; with inline tags inside

tags = *(tag 1*CRLF)

inline-tag = “{” tag “}”

tag = “@” tag-name [“:” tag-specialization] [tag-details]

tag-name = (ALPHA / “\”) *(ALPHA / DIGIT / “\” / “-” / “_”)

tag-specialization = 1*(ALPHA / DIGIT / “-“)

tag-details = *SP (SP tag-description / tag-signature / inline-phpdoc)

tag-description = 1*(CHAR / CRLF)

tag-signature = “(” *tag-argument “)”

tag-argument = *SP 1*CHAR [“,”] *SP

خلاصه فرمت PHPDoc:

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

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

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

توصیف

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

Inline PHPDoc

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

مثال:

/**

* @method int MyMagicMethod(string $argument1) {

* This is the summary for MyMagicMethod.

*

* @param string $argument1 Description for argument 1.

*

* @return int

* }

*/

class MyMagicClass

{

…

}

ارث بری
یک 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

برچسب ها

درباره مدیر محتوا

همچنین بررسی کنید

اشتراک گذاری لوکال هاست با NGROK

    شمازمان زیادی را صرف پیاده سازی پروژه هایتان می کنید، دراین فکر هستید …

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

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

abatech.ir
تمامی حقوق برای اباتک محفوظ است