كثير مايتحدث المبرمجين عن أهمية كتابة التعليقات للمشاريع البرمجية وانها احد اهم عوامل نجاح المشاريع حيث تسهل عمل المبرمجين لفهم ملفات المشروع والبدء بالتطوير بشكل اسرع وانها تعمل على تذكير المبرمج مايعني هذا الجزء من الكود جميعنا عملنا على مشاريع كبيره او صغيره واحتجنا بعد عدة اشهر لتطوير جزء مهم منها ونقف عند ماكتبنا منفجعين وحائرين مايعني هذا ومامعنى هذاك ماذا كنت اقصد بهذا وماهية عمل هذا الكود وبعد عدة ساعات من المحاولات نبدأ التطوير الفعلي لهذا قام المبرمجين بتطوير وتوحيد نظام التعليقات للملفات البرمجية واعتماد قوانين وتنضيمات لها للحد من هذه الظاهرة وتكون نقطة بداية عند فتح اي ملف برمجي هي قراءة التعليق مباشرة لفهم عمل الأكواد المكتوبة في PHP يطلق عليها اسم DocBlock وتم شرحها وتفصيلها في مقالة سابقة يمكنك الإستفادة منها
اضغط هنا
الآن اصبحت مبرمج جيد يهتم بكتابة التعليقات وتنظيمها ووضع امثله لها ماذا بعد ذلك هل يمكن الإستفادة من هذه التعليقات بشكل افضل ومطور عن الوضع التقليدي التي تتطلب مني فتح الملف ثم قراءة التعليق لفهمه ماذا لو اخبرتك انه تم تطوير أداة تقوم بعمل فحص وقرائة ملفاتك البرمجية ثم تحويل هذه التعليقات DocBlock الى مستندات توثيق منسقة ومرتبة وحتى رسم Class diagrams وبكثير من الأمكانيات بأوامر بسيطة ويمكنك مشاركة هذه المستندات مع من ترغب من المطورين في فريقك ليكون الوصول الى المعلومه اسهل وارتب من السابق دون الحاجه لفتح اي ملف لقراءة تعليقاته وفهم عمله هذه الأداة اسمها phpDocumentor واختصارها phpDoc
من يستخدم phpDocumentor:
يستخدم phpDocumentor العديد من الشركات والمطورين حول العالم والكثير من المشاريع الناجحة تستخدمه لتوثيق مشاريعها وتقديمها للمطورين لفهم المشاريع والبدء بالتطوير سوف نذكر البعض هنا
قبل البدء بتثبيت phpDocumentor تأكد ان جهازك يحتوي على كل من
- PHP 5.5 أو أعلى
- intl extension for PHP
- Graphviz اختياري في حال كنت ترغب بتوليد Class diagrams فقط
- تاكد من اعدادات الوقت والتاريخ داخل ملف php.ini بالذات تاكد من timezone انه مفعل وتم تحديد منطقة زمنية صحيحه مثال UTC
لتثبيت phpDocumentor لدينا عدة طرق تستطيع استخدام مايناسبك من هذه الطرق سوف يتم تثبيت phpDocumentor اما بشكل عام Global بجاهزك او بشكل محلي Local على مستوى ملفات مشروعك ويفضل دائما تثبيت phpDocumentor بشكل عام Global حيث هذه الطريقة تسمح لك الوصول وتنفيذ جميع اوامر هذه الأداة بشكل عام ومن اي مكان باستخدام Terminal على عكس التثبيت المحلي Local لن تسطيع تنفيذ اوامر الأداة الا عن طريق الملجد الذي تم تثبيت الأداة بداخله
يمكنك استخدام احد هذه الطرق لتثبيت phpDocumentor
بواسطة PEAR (تثبيت عام)
اذا كنت تستخدم PEAR يمكنك تثبيت phpDocumentor بواسطة تنفيذ هذا الأمر في Terminal
pear channel-discover pear.phpdoc.org ثم تنفيذ هذا الأمر
pear install phpdoc/phpDocumentor بعدها تستطيع تنفيذ اوامر phpDocumentor بشكل عام Global باستخدام الأمر phpdoc عن طريق Terminal
بواسطة Composer (تثبيت محلي)
اذا كنت تستخدم Composer في مشاريعك يمكنك تثبيت phpDocumentor بطريقتين
اول طريقة: عن طريق تحديث ملف composer.json تحت قسم require-dev قم باضافة المكتبة كالتالي
{ "require-dev": { "phpdocumentor/phpdocumentor": "2.*" } } وبعدها قم بتحديث ملفات مشروعك باستخدام composer update او ثبت المكتبات باستخدام composer install
ثاني طريقة: باستخدام اوامر Composer نقوم بتثبيت phpDocumentor بواسطة تنفيذ هذا الأمر في Terminal
composer require --dev phpdocumentor/phpdocumentor بعد تثبيت المكتبة بنجاح نستطيع الوصول وتنفيذ اوامر المكتبة عن طريق ملف phpdoc.php الموجود داخل مجلد /vendor/bin داخل مجلدات مشروعك باستخدام هذا الأمر
مستخدمي MAC OSX و Linux
php vendor/bin/phpdoc مستخدمي Windows
php vendor\bin\phpdoc.bat ملاحظة: phpDocumentor تستهلك وتعتمد على العديد من المكتبات اذا لم تكن هذه الطريقة مناسبة لك قم بتجربة احد الطرق الأخرى
بواسطة PHAR (تثبيت محلي)
كل ماعليك هو تحميل ملف PHAR الخاص بالمكتبة phpDocumentor فقط ووضعه داخل مجلد مشروعك
بواسطة HomeBrew (تثبيت عام)
لمستخدمي انظمة الماك تستطيع تثبيت واستخدام phpDocumentor باستخدام homeBrew بكل بساطة قم بتنفيذ هذا الامر
brew install phpdocumentor وهي من اسهل الطرق والتي استخدمها و تسمح لك بالوصول لجميع اوامر phpDocumentor بشكل عام Global عن طريق الأمر phpdoc في Terminal
طريقة الإستخدام:
للتاكد من تثبيت phpDocumentor بجهازك وعرض جميع الأوامر والمساعدة قم بتنفيذ هذا الأمر في Terminal
phpdoc run -h اذا تم تثبيت phpDocumentor بنجاح سوف يعرض لك التالي
ابسط صورة لكيفية استخدام المكتبة هي نتوجه لمجلد المشروع المراد توثيقه وبعدها نقوم بتنفيذ هذا الأمر في Terminal
phpdoc run -d <SOURCE_DIRECTORY> -t <TARGET_DIRECTORY> لاحظ في هذا الأمر استخدمنا الأمر phpdoc run وبعدها تسطيع استخدام اي من الخيارات او الإعدادات التي توفرها الأداة وهنا استخدمنا d- لتحديد المجلد المراد توثيقه وثم استخدمنا t- لتحديد الملجد المراد حفظ ناتج التوثيق على شكل ملفات HTML
لنفرض ان مشاريعك البرمجية داخل مجلد htdocs انا استخدم MAMP PRO ويمكن الوصول لهذا المجلد بواسطة الأمر cd عن طريق Terminal
cd /Applications/MAMP/htdocs بعدها ننفذ الأمر phpdoc وتزويده بالمجلد المراد توثيقه والمجلد المراد حفظ ناتج التوثيق بواسطة هذا الأمر
phpdoc -d ./3alampro -t ./3alampro/docs/api ستقوم الأداة بتحليل جميع ملفات مشروعك والبحث عن مايمكن توثيقه عن طريق قراءة DocBlock المستخدمه داخل ملفاتك ثم عمل موقع HTML داخل الملجد المحدد لتخزين ناتج التوثيق هذه العمليه سرعتها تعتمد على كبر ملفات مشروعك وممكن ان تاخذ وقت فلا تخاف وارتح واشرب كوبا من القهوة
️ وانتظر باستمتاع لانتهاء عملية التوثيق سيكون الناتج كالتالي بعد تصفحك لمجلد التوثيق من متصفحك
في الختام:
يمكن الاستفادة من التعليقات المكتوبة والمنسقة وتحويلها الى مستندات توثيق باستخدام phpDocumentor ويوجد ادوات منافسة لها مثل الأداة Sami ولك حرية استخدام مايناسبك وفريقك وجدت هذه الأدوات للتسهيل من حياة المبرمج وتسهيل فهم الملفات البرمجية وتبسيطها ليستمع بقية يومه بالتطوير بدون صداع ومحاولة فهم خربشات بقية المبرمجين او حتى خربشاته القديمه
