phpDocumentor به شما این قابلیت رو میده که از پروژه PHP تون یک فایل داکیومنت خروجی بگیرید و داکیومنت نویسی در PHP را انجام دهید.
برای شروع اول باید یاد بگیریم که درست داکیومنت بنویسیم – البته اگر تا به حال می نوشتیم – داکیومنت نوشتن از چندین نظر خیلی خوبه و به کار مون میاد:
اول اینکه اگر پروژه بزرگ و دارای کدهای پیچیده باشه و مخصوصا پس از گذشت مدتی بهش مراجعه کنیم، در درک بهتر اینکه چیکار کردیم، خیلی بهمون کمک می کنه.
دوم اینکه اگر روزی ادامه یک پروژه رو به کس دیگری واگذار کردیم، به درک بهتر کد برای انتقال دانش ادامه اون پروژه به فرد جدید خیلی مفید هست.
و سوم اینکه خیلی از جاها یک داکیومنت خوب می تونه باعث جلوگیری از باگ ها بشه، به اینصورت که نکاتی که ممکنه در انجام تغییرات بعدی فراموش بشه رو در جای درست یادآوری کنه…
همه اینها به شرطی هست که به داکیومنت نویسی و آپدیت اون در طول انجام پروژه، همه تیم پایبند باشن و دلسوزانه و درست انجام بشه.
و اما چه مواردی نیاز به نوشتن داکیومنت دارن؟
And Files
اگر با هریک از موارد بالا آشنایی ندارید، می تونید در سایت php.net توضیحات مرتبط اون رو ببینید.
و اما ساختار داکیومنت نویسی
داکیومنت دارای 3 بخش اصلی هست:
- خلاصه (Summary): معمولا یک خط و توضیح مختصری در رابطه با عنصری که براش داک می نویسیم. به دو روش از توضیحات جدا میشه، یک:آخر خلاصه نقطه و خط بعد توضیحات؛ دوم: با یک خط خالی بین خلاصه و توضیحات.
- توضیحات(Description): (دلخواه است – optional) توضیحات مفصل با جزئیات بیشتر، احتمالا همراه با مثال و…
- مجموعه تگ (A series of tags): تگ ها اطلاعات بیشتری در باره ساختار اصلی میدن، اطلاعات از جمله properies و arguments و…
همانطور که توجه کردید، داکیومنت ها با /** شروع و با */ به پایان میرسن.
تگ ها:
داکیومنت نویسی در PHP شامل 28 نوع تگ تعریف شدن که در زیر لیست شدن و برای اطلاعات بیشتر و توضیحاتشون به آدرس این لینک مراجعه کنید.
می تونید با مراجعه به سایت phpdoc از آنجا دانلود کنید.
ایجاد فایل داکیومنت هم باهاش خیلی آسونه و کافیه با سه دستور زیر آشنا باشید:
-d for a directory,
-f for a file
-t tell it to output your documentation to a folder of your liking. (If you want you can even omit the -t option, in which case the output will be written to a subfolder called output.)
مثال:
در ترمینال میزنید:
$ phpdoc -d ./src -t ./docs/api
این یعنی درون پوشه /src پروژه شما قرار داره و خروجی داکیومنت رو در پوشه /docs/api ذخیره کنه.
