.صافي مستندات xml - وراثة الوثائق

Question

NDoc لديه عنصر XML inheritdoc والذي يسمح لك أن ترث الوثائق عضو من الطبقة الأم (أو تنفيذ واجهة).ومع ذلك, Visual Studio (أيC# compiler) لا يفهم هذا الوسم و يشكو الوثائق لا يجري في الحاضر أو الكامل.حتى لا StyleCop وبعض الأدوات الأخرى.هل هناك بديل النهج ؟ كيف يمكنك أن تذهب نحو الحفاظ على مستندات كاملة ، ولكن دون تكرار XML الأوصاف ؟

Answer 1

أحد البدائل هو الاستخدام GhostDoc - وظيفة إضافية لبرنامج Visual Studio تقوم تلقائيًا بإنشاء التعليقات لك.يؤدي هذا إلى تكرار وصف XML بالطبع، وهو جزء مما تحاول تجنبه - ولكنه على الأقل يفعل ذلك تلقائيًا نيابةً عنك.

ماذا يحدث إذا تركت المستندات بالكامل للطرق الموروثة، أو لتجاوز طرق الواجهة؟أظن أن ذلك يعتمد على كيفية تكوين NDoc، ولكن بالتأكيد في وثائق MSDN يبدو أنه يرث المستندات بشكل طبيعي - وفحص سريع وتقترح لن يتذمر VS عندما لا تنتج مستندات لطريقة موروثة.يستحق المحاولة، بالتأكيد.

Answer 2

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

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

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

وصف قصير من FiXml:بل هو بعد انتهاء المعالج من وثائق XML التي تنتجها C# \ Visual Basic .صافي.فمن تنفيذها MSBuild المهمة, لذلك فمن السهل جدا لدمج أن أي مشروع.وهو يتناول بعض مزعج القضايا المتعلقة كتابة وثائق XML في هذه اللغات:

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

من أجل حل القضايا المذكورة ، الإضافية التالية علامات XML المقدمة:

• <inheritdoc />, <inherited /> tags
• <see cref="..." copy="..." /> سمة في <see/> الوسم.

هنا صفحة ويب و تحميل الصفحة (كسر الروابط).

وأخيرا ، هناك <inheritdoc> الوسم في الرمال - بالتأكيد الأفضل لاستخدامها من نسخة XML التعليقات, ولكن كان لديه بعض العيوب مقارنة FiXml:

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

انظر الرمال هو <inheritdoc> الوصف للحصول على مزيد من التفاصيل.

Answer 3

لقد قمت بإنشاء أداة سطر أوامر للمعالجة اللاحقة لملفات وثائق XML لإضافة دعم للعلامة <inheritdoc/>.

إنه لا يساعد في Intellisense في التعليمات البرمجية المصدر ولكنه يسمح بتضمين ملفات وثائق XML المعدلة في حزمة NuGet وبالتالي يعمل مع Intellisense في حزم NuGet المشار إليها.

يرى www.inheritdoc.io لمزيد من التفاصيل (النسخة المجانية متوفرة).