عرض مشاركة واحدة
  #1  
قديم 05-28-2021, 03:09 AM
الصورة الرمزية الادارة كريم
الادارة كريم 
مشرف سابق
 
تاريخ التسجيل: May 2021
الدولة: مصر
المشاركات: 397
معدل تقييم المستوى: 24
الادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to beholdالادارة كريم is a splendid one to behold


افتراضي توثيق المشاريع البرمجية باستخدام phpDocumentor

 



كثير مايتحدث المبرمجين عن أهمية كتابة التعليقات للمشاريع البرمجية وانها احد اهم عوامل نجاح المشاريع حيث تسهل عمل المبرمجين لفهم ملفات المشروع والبدء بالتطوير بشكل اسرع وانها تعمل على تذكير المبرمج مايعني هذا الجزء من الكود جميعنا عملنا على مشاريع كبيره او صغيره واحتجنا بعد عدة اشهر لتطوير جزء مهم منها ونقف عند ماكتبنا منفجعين وحائرين مايعني هذا ومامعنى هذاك ماذا كنت اقصد بهذا وماهية عمل هذا الكود وبعد عدة ساعات من المحاولات نبدأ التطوير الفعلي لهذا قام المبرمجين بتطوير وتوحيد نظام التعليقات للملفات البرمجية واعتماد قوانين وتنضيمات لها للحد من هذه الظاهرة وتكون نقطة بداية عند فتح اي ملف برمجي هي قراءة التعليق مباشرة لفهم عمل الأكواد المكتوبة في 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 بنجاح سوف يعرض لك التالي
هذا الأمر يعرض لك طرق الإستخدام وجميع انواع الخيارات الممكن استخدامها بواسطة الأمر phpdoc
ابسط صورة لكيفية استخدام المكتبة هي نتوجه لمجلد المشروع المراد توثيقه وبعدها نقوم بتنفيذ هذا الأمر في 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 العديد من الخيارات والأمكانيات حيث تسطيع انشاء ملف phpdoc.xml داخل مجلد مشروع وتضع جميع الإعدادات المراد تنفيذها عند تنفيذ الأمر phpdoc داخل مجلد المشروع وهي جدا بسيطة ممكن الإستفادة من هذه الصفحة phpdoc configuration
في الختام:
يمكن الاستفادة من التعليقات المكتوبة والمنسقة وتحويلها الى مستندات توثيق باستخدام phpDocumentor ويوجد ادوات منافسة لها مثل الأداة Sami ولك حرية استخدام مايناسبك وفريقك وجدت هذه الأدوات للتسهيل من حياة المبرمج وتسهيل فهم الملفات البرمجية وتبسيطها ليستمع بقية يومه بالتطوير بدون صداع ومحاولة فهم خربشات بقية المبرمجين او حتى خربشاته القديمه


الموضوع الأصلي : توثيق المشاريع البرمجية باستخدام phpDocumentor || الكاتب : الادارة كريم || المصدر : منتدى مجمع التطوير

 

رد مع اقتباس