كيف يمكنني توثيق كود C# الخاص بي؟[مغلق]

Question

أقوم بإنشاء الوثائق الخاصة بواجهة برمجة تطبيقات C# الخاصة بنا والتي تحتوي على:

1. نظرة عامة ووصف للحالة الحالية كملف doc/pdf.
2. واجهة برمجة تطبيقات مكتبة فئة في ملف .chm باستخدام Sandcastle.

أسئلة:

1. هل ينبغي علي دمج هذين الملفين في نفس ملف .chm؟ما هي الطريقة الجيدة لدمجهم؟
2. أحتاج إلى استبعاد فئات/حزم معينة.كيف يمكنني تحديد ذلك في SandCastle؟
3. يقوم بإنشاء وثائق لرمز VB ورمز Visual C++.كيف يمكنني تغيير هذا؟أم أتركه مع العلم أنني أستخدم الرمز الآمن فقط؟
4. أين يمكنني العثور على مسار عارض تعليمات HTML 2.x على نظامي؟

يحرر:

التعليقات التي أدلي بها أعلاه على الأساليب والحقول والفئات لا يتم إنشاؤها في الوثائق.

ماذا علي أن أفعل؟

Answer 1

أنصحك باستخدامه منشئ ملف مساعدة Sandcastle من كودبلكس.يمكنك بسهولة تضمين مساحات الأسماء واستبعادها، لكنني غير متأكد من كيفية استبعاد فئة واحدة.يمكنك تعيين الخيار لإنشاء وثائق للفئات العامة/المحمية فقط، لكنني لا أعرف ما إذا كان ذلك سيناسب السيناريو الخاص بك.

يمكنك أيضًا استهداف لغة معينة في SHFB، بالنسبة لسؤالك الثاني.

بالإضافة إلى ذلك، يمكنك استخدام MAML داخل SHFB للتوثيق المفاهيمي، مثل ما ذكرته في ملف doc/pdf.يجب أن تكون قادرًا على الاستخدام Doc2Maml لترحيل الوثائق الموجودة لديك.يعد Doc2Maml جزءًا من DocProject، ولكن يبدو أنك قد تتمكن من تشغيله بشكل مستقل.

تحرير ردا على التعليق:

الاتجاهات خاصة بـ SHFB 1.8.0.1.لا أتذكر الطريقة الدقيقة للقيام بذلك في الإصدار 1.7، لكنني أعتقد أنها مشابهة:

1. ضمن مجموعة "التعليقات" في علامة التبويب "خصائص المشروع"، انقر فوق علامة الحذف الموجودة على يمين "NamespaceSummaries".
2. في قائمة مربعات الاختيار الموجودة في الجزء العلوي الأيسر، قم بإلغاء تحديد أي مساحة اسم تريد استبعادها.

هذه هي أيضًا الشاشة التي تضع فيها ملخصات مساحة الاسم.

Answer 2

بالإضافة إلى قلعة الرمال كما هو مذكور أعلاه، أوصي أيضًا بالنظر إليها FxCop و StyleCop للمساعدة في التأكد من أن التعليمات البرمجية والوثائق الخاصة بك تتوافق مع معايير الامتثال لـ CLS.

Answer 3

يحتوي Sandcastle Help File Builder (SHFB) نفسه على ملف .chm حيث يمكنك العثور على إجابات لأسئلة مثل "كيف يمكنني استبعاد مساحات أسماء أو فئات معينة من المستند الذي تم إنشاؤه؟"

قد تظن أنني أعرف الإجابة وأنني أشعر بالخجل من عدم إخبارك.غير صحيح.لكنني كنت أتصفح المستند الليلة الماضية وشاهدت مدخلاً حول هذا الموضوع بالذات.

لا أعرف لماذا لا تترك فقط أشياء VB وC++؛قد يكون هناك في المستقبل شخص يستخدم لغة (بشكل صادم) ليس سي # مع مكتبتك.عادة ما تكون اللغة قابلة للضبط بواسطة عارض التعليمات، لذلك يمكن لمطوري C# تجاهل بناء جملة VB.

أما بالنسبة للدمج، فإن SHFB لديه آلية لإضافة HTML عشوائيًا في تسلسل هرمي عشوائي.في واجهة المستخدم الرسومية هو هنا:

http://www.freeimagehosting.net/uploads/7de19ea568.jpg

باستخدام هذا، يمكنك تحويل PDF/DOC إلى HTML ثم تضمينه في ملف .chm.