تعليقات وثائق XML مع واجهات وتنفيذ فئة (ES) [مغلقة

Question

أنا توثيق التجمع باستخدام XML وثائق التعليقات, ، منها chm سيتم إنشاء ملف باستخدام sandcastle..

تحتوي تجميعي على واجهات مختلفة، يتم تنفيذ كل منها من قبل فئة واحدة (في سيناريو هذه هي خدمات WCF).

لقد أضفت وثائق إلى الواجهات، هل هناك أي طريقة بالنسبة لي توثيق الأساليب ذات الصلة تلقائيا على الفئات المنفذة؟

Answer 1

يبدو أن هناك أي دعم لمثل هذه التلقائي في SandCastle. ال Sandcastle مساعدة ملف باني على الرغم من أنها تنفذ علامة INHHERTDOC مخصصة.

من موقع shfb:

يتم تضمين الدعم لu003Cinheritdoc /> العلامة التي تتيح لك ترث الوثائق من أنواع الأساس / الأعضاء. يتم تنفيذ ذلك عبر أداة مستقلة حتى يمكن استخدامها أيضا من قبل أدوات الطرف الثالث الأخرى وبناء البرامج النصية. توفر هذه الأداة ميزات تتجاوز تلك الموجودة في مكون البناء المقدمة مع SandCastle.

التحديث الثاني: وفقا ل هذا المنتذري, ، فإن "الدعم" الشامل ل INHHERTITDOC هو من خلال أداة SHFB. خلاصة أسفل أفترض هو، shfb يحل مشكلتك.

Answer 2

لدي إجابة أفضل: FIXML..

من المؤكد أن تعليقات الاستنساخ مع ghostdoc atomineerutils هي بالتأكيد نهج العمل، لكن لديها عيوب كبيرة، على سبيل المثال:

• عندما يتم تغيير التعليق الأصلي (الذي يحدث بشكل متكرر أثناء التطوير)، فإن استنساخه ليس كذلك.
• أنت تنتج كمية هائلة من التكرارات. إذا كنت تستخدم أي أدوات تحليل شفرة المصدر (مثل مكتشف مكررة في Team City)، فستجد بشكل أساسي تعليقاتك.

كما ذكر، هناك <inheritdoc> العلامة في sandcastle., ، ولكن لديها عدد قليل من العيوب بالمقارنة مع FIXML:

• تنتج Sandcastle ملفات تعليمات HTML مجمعة - لا تعدل .xml الملفات التي تحتوي على تعليقات XML المستخرجة. ولكن تستخدم هذه الملفات من قبل العديد من الأدوات، بما في ذلك .NET عاكس ومتصفح الفئة Intellisense في Visual Studio .NET. لذلك إذا كنت تستخدم فقط Sandcastle، فلن ترى وثائق موروثة هناك.
• تطبيق Sandcastle أقل قوة. على سبيل المثال لا<see ... copy="true" />.

يرى Sandcastle's <inheritdoc> وصف لمزيد من التفاصيل.

وصف مختصر FIXML: إنه مستندات بعد معالج XML الناتج عن C # Visual Basic .NET. يتم تطبيق مهمة MSBUILD، لذلك من السهل جدا دمجها لأي مشروع. يتناول القليل من الحالات المزعجة المتعلقة بكتابة وثائق XML هذه اللغات:

• لا يوجد دعم لوراثة الوثائق من الطبقة الأساسية أو الواجهة. أي ينبغي كتابة وثائق لأي عضو متجاوز من الصفر، على الرغم من أنه عادة ما يكون من المرغوب فيه أن يرث على الأقل جزء منه.
• لا يوجد دعم لإدراج قوالب الوثائق الشائعة الاستخدام, ، مثل "هذا النوع مينغلتون - استخدم لها <see cref="Instance" /> الممتلكات للحصول على المثيل الوحيد منه. "، أو حتى" تهيئة مثيل جديد من <CurrentType> صف دراسي."

لحل المشكلات المذكورة، يتم توفير علامات XML الإضافية التالية:

• <inheritdoc />, <inherited /> كذا
• <see cref="..." copy="..." /> السمة في <see/> بطاقة شعار.

هنا صفحة الويب الخاصة بها و تحميل الصفحة.

Answer 3

أداة مثل غوسدادك يمكن أن تولد الوثائق على الفئات المنفذة، عند استخدامها اختصار لوحة المفاتيح. هذا ليس تلقائيا تماما، ولكن يمكن أن يساعد في منع الكثير من لعض النسخ.

ربما يمكن أن يكون الآلي مع البرنامج النصي.

Answer 4

سيقوم AtomineerUtils بتكوين تعليقات تلقائية لك، ويقتلح الوثائق الموجودة من الحمل الزائد والفئة الأساسية المتجاوزة، مما يوفر لك الكثير من المتاعب في تكرار المعلومات التي تكون هناك حاجة إليها.

http://www.atomineer.com/atomineerutils.html.