c# - studio - Comentarios XML-¿Las referencias deben estar completamente calificadas?

generar documentacion visual studio 2017

Question

Básicamente, cuando es realmente necesario (si es que lo hace) usar un xml completo, consulte la referencia:

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

Además, ¿qué hay de hacer referencia 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 que califican completamente 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 enlazar a los archivos de ayuda de .NET Framework o estoy perdiendo el tiempo haciendo referencia a <see cref="T:System.Collections.Generic.ICollection{T}"/> ?

Answer 1

No estás perdiendo el tiempo en <see cref /> -ing the Framework, 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 ha funcionado bastante bien en el pasado.

En cuanto a la calificación completa, no es necesario en la mayoría de los escenarios, sino que depende de sus usos, como Ben . Siempre que lo que usted está haciendo referencia esté dentro del alcance (y cualquiera de los dos debería estarlo, ya que es probable que lo esté utilizando si lo está haciendo referencia o debería agregar el uso para que su código no utilice el formulario completo). sólo el tipo debería ser suficiente.

Answer 2

No puedo hablar por Sandcastle, pero según mi experiencia con otras herramientas, por ejemplo, ReSharper, parece que un tipo debe calificarse si a) no está dentro del alcance o b) está sombreado por otro tipo que es más localmente definido.

En otras palabras, si está using System.Collections.Generic , entonces no tendrá que calificar ICollection{T} . Sin embargo, si define su propia ICollection{T} en el mismo archivo, tendrá que calificar la primera (y la última, ahora que lo pienso).

Answer 3

Tanto Joseph como Ben tocan puntos útiles, pero creo que mi experiencia reciente con Sandcastle puede ser útil:

1. Cuando compila su proyecto, Visual Studio usualmente le dirá de inmediato si su referencia es válida emitiendo una advertencia si no puede resolver una referencia en sus documentos-comentarios, si esta es una referencia a sus propios tipos o tipos de sistema (y VS sí lo hace). honra tus declaraciones "usando").

2. En el caso de tener un tipo local que oculte 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 al calificar completamente el nombre.

3. Se refirió al uso de especificar explícitamente el prefijo de tipo de miembro (por ejemplo, "T: SuperWidget"), pero esto es más importante de lo que la mayoría de las personas se da cuenta: si utiliza un prefijo de tipo de miembro, se requieren nombres completos. Esto está realmente documentado en MSDN pero en la impresión muy fina - vea Procesando el archivo XML . Y para empeorar las cosas, si omite el nombre completo, no recibirá ninguna advertencia en el momento de la compilación (!); simplemente no se genera ningún enlace en la representación final de Sandcastle. Hay otros problemas si especifica explícitamente un prefijo de tipo de miembro - vea la sección Desambiguación y resolución de referencias de mi artículo sobre consejos prácticos sobre Sandcastle, Taming Sandcastle: Guía del programador de .NET para documentar su código .