منتدى فيجوال بيسك لكل العرب | منتدى المبرمجين العرب

نسخة كاملة : مقال- التوثيق في الدوت نت Documenting In .NET
أنت حالياً تتصفح نسخة خفيفة من المنتدى . مشاهدة نسخة كاملة مع جميع الأشكال الجمالية .
كاتب الموضوع : Islam Ibrahim

التوثيق في الدوت نت من الأمور التي يجب المطوِّرين إدراكها وإتقان استخدامها وذلك من أجل تقديم المعلومات الإرشادية لمستخدمي البرامج وكذلك المطوِّرين الآخرين, يمكنك أن تتخيل الجهد المبذول الذي قامت به Microsoft لتأليف MSDN, ومن الغباء أن تتوقع انه قد تمت كتابتها يدويا أي باستخدام أشخاص توكل إليهم هذه المهام, فإن لـ Microsoft أداوت تقوم بتحرير تلك الصفحات بشكل آلي أسهل وأكفأ مما تتصّور.



ومن المزايا لتقنية التوثيق في الدوت نت خصوصاً هو مجانيتها وسهولة استخدامها, بالإضافة إلى
الكفاءة والسرعة في العمل.

في هذا المقال مجموعة من المقالات الفرعية وسأضمنها تباعاَ, وهي:
  • Microsoft Sandcastle
  • CodePlex DocProject and Sandcastle help File Builder
  • Microsoft Assistance Markup Language (MAML)
  • مجموعة من الأمثلة

Microsoft Sandcastle
هي أداة مجانية من Microsoft لتوليد ملفات التوثيق والتي تأخذ شكل MSDN باستخدام تقنية Reflection على تجميعات .NET (.NET Assemblies) ومستندات التعليقات ذات التنسيق XML ((Comments Documentation XML والتي عادة ما تكون موجودة ضمن الملفات المصدر (Source Code), وبإمكانها كذلك توليد الوثائق التي تعتمد على Microsoft Assistance Markup Language (MAML).
تعتمد Microsoft Sandcastle على أدوات سطر الأوامر, ملفات التكوين, أدوات البناء, وملفات تحويل XSLT, والتي تعمل مجتمعة على تحويل الملفات التي تحتوي على التعليقات إلى ملفات التي ملفات المساعدة والتي يمكن عرضها ضمن نظام التعليمات.
لتحميل أحدث إصدار من Microsoft Sandcastle راجع موقع تنزيل Microsoft Sandcastle.

يحتوي Microsoft Sandcastle على العديد من البرامج نذكر منها:
MrefBuilder يقوم بإنشاء ملف بعد القيام بعملية Reflection على التحميع الممرر إليه.
XslTransform يقوم باستلام الملف المخرج من أداة MrefBuilder لتطبيق تحويلات XLS اللازمة إلى ملف XML
BuildAssembler يقوم بتوليد أدوات بناء مؤقتة وفق كل Topic, والتي يتم تعيينها في ملفات XML Maniest
لايقوم Samdcastle بإنشاء ملفات CHM مباشرة وإنما يقوم فقط بتوليد ملفات HTML والبقية تتركها على المشاريع التي قام أعضاء موقع CodePlex بإنشائها.

وبسبب هذه الأدوات الكثيرة ونظرا لأنه فقط مجموعة من أدوات سطر الأوامر, فإنه يصعب استخدام Sandcastle بشكل مباشر لذلك تم إنشاء مجموعة من المشاريع ذات واجهة الاستخدام GUI من قبل CodePlex والتي تبسط العمل إلى حد كبير.
Microsoft Assistance Markup Language (MAML)
هي لغة التوصيف المستندة إلى XML والتي تم تطويرها من قبل فريق Microsoft User Assistance Platform لتقديم المساعدة للمستخدمين لنظام التشغيل Windows Vista بعض الميزات من هذه اللغة تم تضمينها في Microsoft .NET Framework 2.0 و بشكل كامل في .NET 3.
تركيب محتوى MAML ينقسم إلى عدة أنواع:
• Conceptual
• Error Message
• Glossary
• How-To
• Orientation
• Reference
• Reference With Syntax
• Reference Without Syntax
• Sample
• SDK Technology Architecture
• SDK Technology Code Directory
• SDK Technology Orientation
• SDK Technology Scenarios
• SDK Technology Summary
• Troubleshooting
• User Interface Reference
• Walkthrough
• Whitepaper
• XML Reference
يمكن ترجمة محتوى MAML إلى عدة تنسيقات منها: HTML, DHTML, XAML, RTF.
للمزيد من المعلومات حول MAML راجع MAML على Wikipedia
CodePlex DocProject

معلومات عن المشروع: البرنامج مفتوح المصدر , مجاني. يحتوي على Add-in لتسهيل العمل
على نسختى Visual Studio 2005 و Visual Studio 2008 النسخة Professional أو Express.
موقع التحميل: (يتاح لك التحميل بعد الموافقة على اتفاقية الترخيص) من هنا


تجربة البرنامج

ابعد تثبيت البرنامج افتح Visual Studio 2005 أو Visual Studio 2008
ستلاحظ وجود ToolBox جديد كما في الشكل


ابدا مشروع DocProject جديد



بعد ذلك سيظهر معالج تكوين المشروع اتبع الخطوات التالية:





بعد إنشاء المشروع أضف إلى Solution مشروع Class Library جديد:




بعد ذلك اضف هذا المشروع كمرجع إلى المشروع DocProject3 الذي أنشاناه




عد إلى Class.vb واضف التعليقات التالية في أعلى الClass.


كود :
''' <summary>
''' Some description in here.
''' بعض التعليقات هنا
''' </summary>
في النهاية أنقر فوق Build للمشروع DocProject3

سيحتاج الأمر وقتا اطول كلما زاد عدد الفئات وحجمها والتي اضفتها كمرجع للمشروع الرئيسي

ألق نظره على جزء Output حيث يتم تكوين ملف CHM النهائي وتمر عملية Build خلال عدة مراحل


عند الانتهاء من عملية Building سيظهر في تقرير ال OutPut رسالة نجاح العملية:


في شريط الأداوت
سترى زر التعليمات مفعلا كما في الصورة وهو دليل نجاح عملية الـ Building


وهذا هو ملف CHM النهائي


يتبع...
استخدام MAML مع DocProject

يمكِّنك DocProject من إضافة مواضيع ذات المحتوى المفاهيمي Conceptual Topics لشرح فكرة معينة عن طريقة عمل برنامجك أو مكتباتك, بالإضافة إلى إمكانية كتابة المقالات الإرشادية Walkthrough Topics, وغيرها من أنواع المواضيع الذي سبق ذكرها في قسم MAML )راجع أعلى الموضوع). يقوم DocProject بترجمة الملفات ذات محتوى MAML إلى ملفات HTML ثم بناء ملف CHM النهائي, يتم كل ذلك اعتمادا على Microsoft Sandcastle. لتحرير مواضيع المحتوى المفاهيمي يمكنك الاعتماد على محرّر XML الخاص بـ Visual Studio أو استخدام Microsoft XML Notepad ويمكنك تحميلها من خلال هذا الرابط
نقطة أخرى مهمة لم أشر في بداية الموضوع لها هي ضرورة وجود Microsoft Help Workshop والذي يحتوي الأدوات الضرورية لبناء ملفات CHM ويمكنك تحميله من هذا الرابط

في الخطوة التالية سأشرح كيفية إضافة موضوع ذو محتوى مفاهيمي إلى المشروع الذي أشاناه سابقا.
افتح المشروع الذي أنشأته سابقا من خلال Visual Studio.
من خلال أداة Toolbox والمسماة DocProject –Sandcastle, أنقر فوق الزرshow the topic explorer .
سيظهر إطار جديد ,والمسمى Topic Explorer ويحتوي على جزئين ToolBox علوي + أداة treeView والتي تمثل شجرة المواضيع وستظهر كما هي في ملف CHM الناتج



انقر فوق الزر الظاهر كما في الصورة



ستلاحظ إضافة ملف جديد باسم New Conceptual Topic بالامتداد الجديد AML والذي سبق الحديث عنه, طبعا يمكنك إعادة تسمية الملف كما ترغب



لاحظ كذلك أن هذا الموضوع يحتوي على معرف GUID يقوم هذا المعرف بتمييز الموضوع عن غيره لإضافته لاحقا كارتباط Link
ستلاحظ أيضا ظهور محتوى الملف في محرر XML الخاص بـ Visual Studio ويظهر كما في الصورة



قم ببناء مشروعك من جديد ولاحظ ملف CHM الناتج سيكون شبيه بالتالي


يتبع...
Sandcastle Help File Builder

من المشاريع الأخرى المفتوحة المصدر والتي يقدمها موقع CodePlex, هي Sandcastle Help File Builder والذي يعمل بشكل مستقل عن Visual Studio وهذا سيفيد مستخدمي نسخ Visual Studio Express, يتميّز SHFB عن DocProject بدعمه الكامل لإدارة وتحرير مواضيع المحتوى المفاهيمي Conceptual Topics, من خلال احتوائه على محرّر MAML خاص بالبرنامج (يعتمد على أحد منتجات Sharpdevelop), شبيه بمحرر XML الخاص بـ Visual Studio, إلا أنه ليس متطوراً جدا, ويقوم حاليا مطوِّر المشروع Dave Secton بتطوير محرِّر MAML مرئي لتوفير الجهد والوقت على مصممي التعليمات.



يمكنك تحميل SHFB من موقع CodePlex على هذا الرابط (بعد الموافقة على اتفاقية الترخيص)
طبعا البرنامج لتطلب وجود .NET Framework 2.0
افتح البرنامج من القائمة Start

عذرا لاني لم استطع رفع الصور لخلل فني في المنتدى

ابدأ مشروعًا جديدًا وليكن Peoject1

ستلاحظ ظهور PropertyGrid والتي تمثل خصائص المشروع يمكنك التحكم بها والتعرف عليها لاحقا.
في الجزء الأيمن من الصورة مستكشف المشروع وهو الذي يمكنك من خلاله إضافة محتوى التعليمات

للبد في العمل

من مستكشف المشاريع وفي البند Documentation sources انقر بزر الماوس الأيمن واختر Add documentation source

حيث من الممكن أن تكون هذه المصادر CLR Excecutable أو ملفات DLL أو ملفات تعليقات XML التي يقوم Visual Studio بإنشائها عند بناء المشاريع. أو حتى مشاريع Visual Studio.

حدد على سبيل المثال ملف DLL قمت بإنشائه باستخدام Visual Studio أو أضف حلاً Solution أو Project مكتوب بلغة VB.NET أو C#. في المثال التالي استخدمت ملف DLL واسمه Test.

من شريط القوائم اختر Documentation ثم قم بعمل Build. ستظهر علامة تبويب جديدة Build Output بجانب خصائص المشروع , عند الانتهاء من عملية البناء ستظهر رسالة Build completed successfully في آخر السجل.

عندها يمكنك تصفح ملف CHM الناتج من خلال شريط القوائم –) Documentation ا-) View Help File.