تعليقات شمل - يجب أن نرى المراجع تكون مؤهلة تماما?

Question

في الأساس ، عندما يكون من الضروري حقا (على كل حال) لاستخدام شمل مؤهل بالكامل انظر المرجع:

<see cref="T:MyNamespace.Sub.MyType"/> //Option 1
<see cref="T:MyType"> //Option 2

أيضا, ماذا عن الرجوع إلى كائنات الإطار الصافي?

<see cref="T:System.Collections.Generic.ICollection{T}"/> //Option 1
<see cref="T:ICollection{T}"/> //Option 2

وأنا أفهم أن العناصر المؤهلة تماما سوف تسمح دائما القلعة الرملية مايكروسوفت لربط الأمور بشكل صحيح, ولكن هل من الضروري لكل شيء ليكون مؤهلا بشكل كامل?

---

ملاحظة جانبية:هل ستتمكن مايكروسوفت ساندكاسل من الارتباط بملفات تعليمات إطار العمل الصافي أم أنني أضيع وقتي من خلال الرجوع <see cref="T:System.Collections.Generic.ICollection{T}"/>?

Answer 1

كلاهما جوزيف و بن أتطرق إلى النقاط المفيدة ولكن أعتقد أن تجربتي الأخيرة في Sandcastle قد تكون مفيدة:

1. عندما تقوم بتجميع مشروعك، عادةً ما يخبرك Visual Studio على الفور ما إذا كان المرجع الخاص بك صالحًا عن طريق إصدار تحذير إذا لم يتمكن من حل مرجع في تعليقات المستندات الخاصة بك، سواء كان هذا مرجعًا لأنواعك الخاصة أو لأنواع النظام (و VS يفعل ذلك احترم عبارات "الاستخدام" الخاصة بك).

2. في سيناريو وجود نوع محلي يخفي نوع النظام، هناك حالتان يجب مراعاتهما:توقيعك يؤهل نوعك بشكل فريد (المشمول في (1) أعلاه)، أو أن توقيعك يكرر نوع النظام تمامًا.تتطلب الحالة الأخيرة توضيحًا صريحًا من خلال تأهيل الاسم بشكل كامل.

3. لقد تطرقت إلى استخدام تحديد صراحة ل بادئة نوع العضو (على سبيل المثال"T:SuperWidget")، ولكن هذا أكثر أهمية مما يدركه معظم الناس:إذا كنت تستخدم بادئة نوع العضو، فستكون هناك أسماء مؤهلة بالكامل مطلوبة.تم توثيق هذا بالفعل على MSDN ولكن في ملف جداً طباعة جيدة - انظر معالجة ملف XML.ومما يزيد الطين بلة، إذا قمت بحذف الاسم المؤهل بالكامل الذي تحصل عليه دون تحذير في وقت البناء(!);ببساطة لم يتم إنشاء أي رابط في عرض Sandcastle النهائي.هناك مشكلات أخرى إذا قمت بتحديد بادئة نوع العضو بشكل صريح - راجع توضيح وحل المراجع قسم من مقالتي عن نصائح Sandcastle العملية، ترويض قلعة الرمل:دليل مبرمج .NET لتوثيق التعليمات البرمجية الخاصة بك.

Answer 2

لا أستطيع التحدث عن القلعة الرملية ، ولكن بناء على تجربتي مع أدوات أخرى على سبيل المثال.ريشاربر ، يبدو أن النوع يحتاج إلى أن يكون مؤهلا إذا أ) لم يكن في النطاق أو ب) يتم تظليله بنوع آخر محدد محليا أكثر.

وبعبارة أخرى ، إذا كنت using System.Collections.Generic, ، إذن لن تضطر إلى التأهل ICollection{T}.إذا كنت يحدث لتعريف بنفسك ICollection{T} واجهة في نفس الملف ، ومع ذلك ، يمكنك ويل يجب أن تؤهل السابق (وكذلك الأخير ، تعال إلى التفكير في الأمر).

Answer 3

أنت لا تضيع وقتك في <see cref />- جي الإطار ، في رأيي.يجب أن يكون مزود مساعدة فيسوال ستوديو قادرا على اعتراض وتفسير في وقت التشغيل عندما يتم إجراء المكالمة لهذا الموضوع مساعدة.أنا لم تستخدم في الآونة الأخيرة ، لكنها عملت بشكل جيد جدا في الماضي.

أما بالنسبة للتأهل الكامل ، فإنه ليس هناك حاجة في معظم السيناريوهات ، ولكن يعتمد على استخداماتك ، كما ذكر بن.طالما أن ما تشير إليه في النطاق (ويجب أن يكون إما ، حيث من المحتمل أن تستخدمه إذا كنت تشير إليه ، أو يجب عليك إضافة الاستخدام بحيث لا تستخدم الشفرة النموذج المؤهل بالكامل) ، فقط يجب أن يكون النوع كافيا.