نام در حال استفاده

یک برچسب در حال حاضر با نام شاخه ارائه شده وجود دارد. بسیاری از دستورات GIT نام برچسب و شاخه را می پذیرند ، بنابراین ایجاد این شاخه ممکن است باعث رفتار غیر منتظره شود. آیا مطمئن هستید که می خواهید این شاخه را ایجاد کنید؟

استانداردهای FIG / پیشنهادی / phpdoc. md

• به پرونده T بروید
• به خط L بروید
• مسیر کپی
• پیوند ثابت را کپی کنید

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

25 همکار

کاربرانی که در این پرونده کمک کرده اند

• با دسک تاپ باز کنید
• مشاهده خام
• محتوای خام را کپی کنید و محتوای خام را کپی کنید

   

محتوای خام را کپی کنید

محتوای خام را کپی کنید

فهرست مطالب

هدف اصلی این PSR ارائه تعریف کامل و رسمی از استاندارد PHPDOC است. این PSR از سلف خود ، استاندارد De-Facto PHPDOC مرتبط با PhpDocumentor 1. x ، برای پشتیبانی از ویژگی های جدیدتر در زبان PHP و پرداختن به برخی از کاستی های قبلی خود منحرف می شود.

این سند نباید:

• استانداردی را برای اجرای حاشیه نویسی از طریق PHPDOC شرح دهید. اگرچه این امر تطبیق پذیری را ارائه می دهد که باعث می شود PSR بعدی بر اساس شیوه های فعلی ایجاد شود. برای اطلاعات بیشتر در مورد این موضوع به فصل 5. 3 مراجعه کنید.
• بهترین شیوه ها یا توصیه های مربوط به استانداردهای برنامه نویسی را در مورد استفاده از استاندارد PHPDOC شرح دهید. این سند محدود به مشخصات رسمی نحو و قصد است.

2. کنوانسیون های مورد استفاده در این سند

کلمات کلیدی "باید" ، "نباید" ، "مورد نیاز" ، "باید" ، "نباید" ، "باید" ، "نباید" ، "توصیه شده" ، "ممکن است" و "اختیاری" در این سندهمانطور که در RFC 2119 شرح داده می شود ، تفسیر می شود.

"PHPDOC" بخشی از مستندات است که اطلاعات مربوط به جنبه های "عنصر ساختاری" را ارائه می دهد.

توجه به این نکته حائز اهمیت است که یک PHPDOC و یک Docblock دو موجود جداگانه هستند. Docblock ترکیبی از یک DocComment است که نوعی اظهار نظر و یک موجودیت PHPDOC است. این موجودیت PHPDOC است که حاوی نحو همانطور که در این مشخصات شرح داده شده است (مانند توضیحات و برچسب ها).

"عنصر ساختاری" مجموعه ای از سازه های برنامه نویسی است که ممکن است قبل از یک Docblock انجام شود. این مجموعه شامل سازه های زیر است:

• نیاز (_once)
• شامل (_once)
• طبقه
• رابط
• ویژگی
• عملکرد (از جمله روش ها)
• ویژگی
• ثابت
• متغیرها ، چه دامنه محلی و چه جهانی.

توصیه می شود قبل از "عنصر ساختاری" با یک مدرک در جایی که تعریف شده است و نه با هر استفاده. این معمول است که Docblock از یک عنصر ساختاری مقدم باشد اما ممکن است با تعداد مشخصی از خطوط خالی از هم جدا شود.

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

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

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

"DocComment" نوع خاصی از نظر است که باید

• با دنباله شخصیت شروع کنید /** و به دنبال آن یک شخصیت Whitespace
• پایان با */ و
• خطوط صفر یا بیشتر در بین آنها وجود دارد.

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

مثال تک خط:

"Docblock" یک "DocComment" است که حاوی یک ساختار "PHPDOC" واحد است و نمایانگر اصلی منبع در منبع است.

"TAG" یک قطعه از اطلاعات متا در مورد "عنصر ساختاری" یا یک مؤلفه آن است.

"نوع" تعیین اینکه چه نوع داده با یک عنصر همراه است. این معمولاً هنگام تعیین مقادیر دقیق آرگومان ها ، ثابت ها ، خواص و موارد دیگر استفاده می شود.

برای اطلاعات بیشتر در مورد انواع ، به پیوست A مراجعه کنید.

"fqsen" مخفف نام عناصر ساختاری کاملاً واجد شرایط است. این نماد بر روی نام کلاس کاملاً واجد شرایط گسترش می یابد و برای شناسایی اعضای کلاس/رابط/صفت و اصول FQCN به رابط ها ، صفات ، کارکردها و ثابت های جهانی ، یک علامت اضافه می کند.

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

• فضای نام: فضای من
• عملکرد: my face myfunction ()
• ثابت: من فضا my_constant
• کلاس: My Space MyClass
• رابط: My Space MyInterface
• صفت: my face mytrait
• روش: my face myclass :: mymethod ()
• ملک: من face myclass :: $ my_property
• ثابت کلاس: My Face MyClass :: my_constant

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

4. اصول اساسی

PHPDOC همیشه باید در "DocComment" موجود باشد. ترکیبی از این دو "Docblock" نامیده می شود.

یک Docblock باید مستقیماً مقدم "عنصر ساختاری" باشد

5. قالب PHPDOC

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

نمونه های استفاده در فصل 5. 4 گنجانده شده است.

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

خلاصه باید با دو شکست پی در پی به پایان برسد ، مگر اینکه این تنها محتوای موجود در PHPDOC باشد.

اگر توضیحی ارائه شده باشد ، باید خلاصه آن باشد. در غیر این صورت توضیحات خلاصه در نظر گرفته می شود ، تا پایان خلاصه.

از آنجا که خلاصه ای با عنوان فصل قابل مقایسه است ، استفاده از قالب بندی کم تا حد ممکن مفید است. به همین ترتیب ، برخلاف توضیحات (به فصل بعدی مراجعه کنید) ، هیچ توصیه ای برای پشتیبانی از یک زبان علامت گذاری انجام نشده است. این صریحاً به برنامه اجرایی واگذار شده است که آیا می خواهد از این امر پشتیبانی کند یا نه.

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

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

کاربردهای متداول برای توضیحات (در میان دیگران) است:

• برای ارائه جزئیات بیشتر از خلاصه در مورد آنچه این روش انجام می دهد.
• برای مشخص کردن اینکه عناصر کودک یک آرایه ورودی یا خروجی یا شیء چیست ، تشکیل شده است.
• برای ارائه مجموعه ای از موارد استفاده مشترک یا سناریوهایی که در آن ممکن است "عنصر ساختاری" اعمال شود.

برچسب ها راهی را برای نویسندگان فراهم می کند تا داده های متا مختصر را در مورد "عنصر ساختاری موفق" تهیه کنند. هر برچسب روی یک خط جدید شروع می شود و به دنبال آن یک علامت AT (@) و یک نام برچسب ، و پس از آن فضای سفید و متا داده (از جمله توضیحات) انجام می شود.

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

param string $ argument1 این یک پارامتر است.

برچسب فوق از یک نام ("پارام") و متا-داده ("رشته $ argument 1 این یک پارامتر است.") که در آن داده های متا به "نوع" ("رشته") ، نام متغیر ("تقسیم می شود ("$ استدلال ') و توضیحات ("این یک پارامتر است.").

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

بنابراین ، برچسب های زیر از نظر معنایی یکسان هستند:

تنوع این امر جایی است که به جای توضیحات ، از امضای برچسب استفاده می شود. در بیشتر موارد ، برچسب در واقع "حاشیه نویسی" خواهد بود. امضای TAG قادر به ارائه حاشیه نویسی با پارامترهای مربوط به عملکرد آن است.

اگر امضای برچسب موجود باشد ، نباید توضیحی در همان برچسب وجود داشته باشد.

داده های متا تهیه شده توسط برچسب ها می تواند منجر به تغییر رفتار واقعی زمان اجرای "عنصر ساختاری" موفق شود ، که در این صورت اصطلاح "حاشیه نویسی" معمولاً به جای "برچسب" استفاده می شود.

نام های برچسب نشان می دهد که چه نوع اطلاعاتی توسط این برچسب نشان داده شده است ، یا در صورت حاشیه نویسی ، که باید این رفتار را به "عنصر ساختاری" موفق تزریق کرد.

در حمایت از حاشیه نویسی ، اجازه می دهد مجموعه ای از برچسب ها را که به طور خاص برای یک برنامه شخصی یا زیر مجموعه برنامه ها طراحی شده است ، معرفی کنید (و بنابراین تحت پوشش این مشخصات قرار نمی گیرد).

این برچسب ها یا حاشیه نویسی ها باید یک فضای نام را توسط هر یک از آنها فراهم کنند

• پیشوند نام برچسب با فضای نام PHP یا توسط
• پیشوند نام برچسب با یک نام فروشنده واحد و به دنبال آن یک Hyphen.

نمونه ای از پیشوند نام برچسب با یک فضای نام به سبک PHP (برش پیشوند اختیاری است):

توجه: استاندارد PHPDOC فرضیه هایی را در مورد معنی یک برچسب ایجاد نمی کند ، مگر اینکه در این سند یا موارد اضافی یا پسوند بعدی مشخص شده باشد.

این بدان معناست که تا زمانی که یک عنصر فضای نام پیشوند ارائه شود می توانید از نام مستعار فضای نام استفاده کنید. بنابراین موارد زیر نیز قانونی است:

کتابخانه یا برنامه شخصی شما ممکن است نام مستعار فضای نام را بررسی کند و از این طریق FQCN تهیه کند. این هیچ تاثیری در این استاندارد ندارد.

نکته مهم: ابزارهایی که از استاندارد PHPDOC استفاده می کنند ممکن است نام های نامگذاری شده در آن برنامه را تفسیر کرده و از رفتار سفارشی استفاده کنند.

نمونه ای از نام برچسب پیشوند با نام فروشنده و هیفن:

نام های برچسب هایی که با یک فروشنده یا فضای نام پیشوند نیستند ، باید در فهرست برچسب PSR و/یا هرگونه ضمیمه رسمی توضیح داده شود.

5. 3. 2. تخصص

به منظور ارائه روشی برای ارائه ظرافت در برچسب های تعریف شده در این استاندارد ، اما بدون گسترش مجموعه پایه ، ممکن است یک تخصص برچسب پس از نام برچسب با اضافه کردن یک روده بزرگ و به دنبال آن یک رشته ارائه شود که توضیحات ظریف تری ارائه می دهدبرچسبلیست تخصص های برچسب پشتیبانی شده در کاتالوگ برچسب PSR نگهداری نمی شود ، زیرا ممکن است با گذشت زمان تغییر کند. سند برچسب TAG PSR Meta ممکن است شامل یک سری توصیه ها بر اساس نام در هر برچسب باشد ، اما پروژه ها در صورت لزوم می توانند تخصص های برچسب خود را انتخاب کنند.

نکته مهم: ابزارهایی که از استاندارد PHPDOC استفاده می کنند ممکن است تخصص های برچسب را که توسط آن برنامه ثبت شده اند ، تفسیر کرده و از رفتار سفارشی استفاده کنند ، اما فقط انتظار می رود نام برچسب قبلی را مطابق با فهرست برچسب PSR اجرا کنند.

SEE: واحد تست نقشه برداری EntityTest :: testgetId

برچسب فوق از یک نام ("نگاه کنید به") و تخصص برچسب ("آزمون واحد") ، و بنابراین رابطه ای با آزمون واحد برای روش روند کار تعریف می کند.

5. 3. 3. امضای برچسب

امضاهای TAG معمولاً برای تهیه حاشیه نویسی برای تهیه متا داده های اضافی خاص برای برچسب فعلی استفاده می شود.

متا داده های عرضه شده می تواند بر رفتار حاشیه نویسی مالکیت تأثیر بگذارد و به همین ترتیب بر رفتار "عنصر ساختاری" جانشین تأثیر بگذارد.

محتوای یک امضا با استفاده از نوع برچسب (همانطور که در نام برچسب توضیح داده شده است) تعیین می شود و فراتر از محدوده این مشخصات قرار می گیرد. با این حال ، یک علامت گذاری برچسب نباید با توضیحات یا شکل دیگری از متا داده ها دنبال شود.

مثالهای زیر برای نشان دادن استفاده اساسی از Docblocks استفاده می شود. توصیه می شود لیست برچسب های موجود در کاتالوگ برچسب PSR را بخوانید.

یک مثال کامل می تواند به این شکل باشد:

همچنین مجاز به حذف توضیحات است:

یا حتی بخش برچسب ها را نیز حذف کنید (هرچند که تشویق نمی شود ، زیرا اطلاعات مربوط به پارامترها و مقدار بازگشت را از دست نمی دهید):

یک Docblock همچنین ممکن است یک خط واحد داشته باشد:

پیوست A. انواع

یک نوع تعریف ABNF زیر را دارد:

هنگامی که از "نوع" استفاده می شود ، کاربر انتظار می رود یک مقدار یا مجموعه ای از مقادیر را به شرح زیر باشد.

هنگامی که "نوع" از انواع مختلفی تشکیل شده است ، پس از آن باید با علامت نوار عمودی (|) برای نوع اتحادیه یا آمپر (و) برای نوع تقاطع از هم جدا شوند. هر مترجمی که از این مشخصات پشتیبانی می کند باید این موضوع را تشخیص دهد و "نوع" را قبل از ارزیابی تقسیم کند.

مثال اتحادیه:

نوع تقاطع مثال:

var myclass & phpunit framework mockobject mockobject $ mymockobject

مقدار نشان داده شده توسط "نوع" می تواند یک آرایه باشد. نوع باید به دنبال قالب یکی از گزینه های زیر تعریف شود:

نامشخص: هیچ تعریفی از محتوای آرایه ارائه شده ارائه نشده است. مثال: retu آرایه

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

مثال: retu int []

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

مشخص شده به عنوان حاوی انواع مختلفی: تعریف نوع خواننده را از نوع هر مقدار آرایه مطلع می کند. هر مقدار می تواند از هر یک از انواع داده شده باشد. مثال: retu (int | رشته) []

نام کلاس معتبر

یک نام کلاس معتبر بر اساس زمینه ای که در آن ذکر شده است مشاهده می شود. بنابراین ممکن است این یک نام کلاس کاملاً واجد شرایط (FQCN) باشد یا یک نام محلی در صورت وجود در یک فضای نام.

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

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

یک کلمه کلیدی هدف از این نوع را تعریف می کند. هر عنصر توسط یک کلاس تعیین نمی شود بلکه هنوز هم شایسته طبقه بندی برای کمک به توسعه دهنده در درک کد تحت پوشش Docblock است.

توجه داشته باشید:

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

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

کلمات کلیدی زیر توسط این PSR شناخته می شوند:

BOOL: عنصری که این نوع در آن اعمال می شود ، فقط دارای حالت صحیح یا نادرست است.

int: عنصری که از این نوع استفاده می کند یک عدد کامل یا عدد صحیح است.

Float: عنصری که از این نوع استفاده می کند یک عدد مداوم یا واقعی است.

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

شی: عنصری که از این نوع استفاده می کند ، نمونه ای از یک کلاس نامشخص است.

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

تکرار پذیر: عنصری که از این نوع استفاده می کند ، یک آرایه یا شیء قابل عبور در هر تعریف PHP است.

منبع: عنصری که از این نوع استفاده می کند ، یک منبع در هر تعریف PHP است.

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

باطل: این نوع معمولاً فقط در تعیین نوع بازگشت یک روش یا عملکرد استفاده می شود ، و این نشان می دهد "هیچ چیز برگردانده نمی شود" ، و بنابراین کاربر نباید به هیچ مقدار برگشتی اعتماد کند.

مثال 1:

در مثال بالا ، هیچ بیانیه بازگشت مشخص نشده و بنابراین مقدار بازده تعیین نمی شود.

مثال 2:

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

NULL: عنصری که از این نوع استفاده می کند یک مقدار تهی است یا از نظر فنی وجود ندارد.

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

مثال 1:

این نوع معمولاً در رابطه با نوع دیگری مورد استفاده قرار می گیرد تا نشان دهد که ممکن است هیچ چیز بازگردانده نشود.

مثال 2:

CALLABLE: عنصری که از این نوع استفاده می کند ، اشاره گر برای یک تماس عملکردی است. این ممکن است مطابق با تعریف PHP باشد.

FALSE یا TRUE: عنصری که از این نوع استفاده می کند ، مقدار صحیح یا نادرست را خواهد داشت. هیچ مقدار دیگری از این عنصر بازگردانده نمی شود.

خود: عنصری که از این نوع استفاده می کند از همان کلاس است که در ابتدا عنصر مستند در آن قرار دارد.

مثال:

روش C در کلاس A موجود است. Docblock بیان می کند که مقدار بازگشت آن از نوع خود است. به همین ترتیب ، روش C نمونه ای از کلاس A را برمی گرداند.

این ممکن است به موقعیت های گیج کننده منجر شود که میراث درگیر می شود.

مثال (وضعیت مثال قبلی هنوز هم اعمال می شود):

کلاس B کلاس A را گسترش می دهد و روش c را دوباره تعریف نمی کند. به همین ترتیب ، می توان از روش C از کلاس B استفاده کرد.

در این شرایط ، ابهام ممکن است به عنوان خود به عنوان کلاس A یا B تعبیر شود. در این موارد ، خود باید به عنوان نمونه ای از کلاس تعبیر شود که در آن اسناد حاوی نوع خود نوشته شده است.

در مثالهای بالا ، خود همیشه باید به کلاس A مراجعه کند ، زیرا با روش C در کلاس A تعریف شده است.

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

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

این کلمه کلیدی به همان روشی که کلمه کلیدی برای اتصال استاتیک دیررس (نه روش استاتیک ، خاصیت و نه اصلاح کننده متغیر) رفتار می کند ، همانطور که توسط PHP تعریف شده است.

$ this: عنصری که از این نوع استفاده می کند ، همان نمونه دقیق کلاس فعلی در متن داده شده است. به همین ترتیب ، این نوع یک نسخه دقیق تر از استاتیک است ، زیرا نمونه برگشتی نه تنها باید در یک کلاس باشد بلکه همان نمونه نیز هست.

این نوع اغلب به عنوان مقدار بازده برای روش های اجرای الگوی طراحی رابط Fluent استفاده می شود.

هرگز: نشان می دهد که عنصر قصد بازگشت به هر چیزی را ندارد و همیشه استثنا را می اندازد یا برنامه را به طور غیر طبیعی خاتمه می دهد (مانند با فراخوانی عملکرد کتابخانه).