Comentarios XML: ¿las referencias deberían estar completamente calificadas?

Question

Básicamente, ¿cuándo es realmente necesario (si es que es necesario) utilizar un xml totalmente calificado? Consulte la referencia:

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

Además, ¿qué pasa con las referencias a los objetos de .NET Framework?

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

Entiendo que los elementos totalmente calificados siempre permitirán que Sandcastle de Microsoft vincule las cosas correctamente, pero ¿es necesario que todo esté completamente calificado?

---

Nota al margen:¿Podrá Microsoft Sandcastle vincularse a los archivos de ayuda de .NET Framework o estoy perdiendo el tiempo haciendo referencias? <see cref="T:System.Collections.Generic.ICollection{T}"/>?

Answer 1

Ambos Joseph y ben Toco puntos útiles, pero creo que mi reciente experiencia en Sandcastle puede ser útil:

1. Cuando compila su proyecto, Visual Studio generalmente le dirá inmediatamente si su referencia es válida emitiendo una advertencia si no puede resolver una referencia en sus comentarios de documento, ya sea una referencia a sus propios tipos o a tipos de sistema (y VS no respete sus declaraciones de "uso").

2. En el caso de tener un tipo local que enmascare un tipo de sistema, hay dos casos a considerar:su firma califica de manera única su tipo (cubierto por (1) arriba), o su firma duplica exactamente un tipo de sistema.El último caso requiere una desambiguación explícita calificando completamente el nombre.

3. Usted mencionó el uso de especificar explícitamente el prefijo de tipo de miembro (p.ej."T:SuperWidget"), pero esto es más significativo de lo que la mayoría de la gente cree:si utiliza un prefijo de tipo de miembro, entonces nombres completos son requeridos.En realidad, esto está documentado en MSDN, pero en el muy letra pequeña - ver Procesando el archivo XML.Y para empeorar las cosas, si omite el nombre completo obtendrá sin advertencia en el momento de la construcción (!);simplemente no se genera ningún vínculo en la representación final de Sandcastle.Hay otros problemas si especifica explícitamente un prefijo de tipo de miembro; consulte la Desambiguación y resolución de referencias sección de mi artículo sobre consejos prácticos sobre castillos de arena, Domar el castillo de arena:Una guía del programador .NET para documentar su código.

Answer 2

No puedo hablar por Sandcastle, pero según mi experiencia con otras herramientas, p.ReSharper, parece que un tipo necesita ser calificado si a) no está dentro del alcance ob) está sombreado por otro tipo que está definido más localmente.

En otras palabras, si eres using System.Collections.Generic, entonces no tendrás que calificar ICollection{T}.Si por casualidad defines el tuyo ICollection{T} interfaz en el mismo archivo, sin embargo, usted voluntad Hay que matizar el primero (así como el segundo, ahora que lo pienso).

Answer 3

No estás perdiendo el tiempo en <see cref />-ing el Marco, en mi opinión.El proveedor de ayuda de Visual Studio debería poder interceptar e interpretar en tiempo de ejecución cuando se realiza la llamada para ese tema de ayuda.No lo he usado recientemente, pero funcionó bastante bien en el pasado.

En cuanto a la calificación completa, no es necesaria en la mayoría de los escenarios, pero depende de sus usos, ya que Ben ha mencionado.Siempre y cuando lo que está haciendo referencia esté dentro del alcance (y debería estarlo, ya que es probable que lo esté usando si lo está haciendo referencia, o debe agregar el uso para que su código no use el formulario completo), sólo el tipo debería ser suficiente.