Comentarios XML - ¿Debería ver referencias completas?

Básicamente, cuándo es realmente necesario (si es que es necesario) utilizar un xml completo ver referencia: 

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

Además, ¿qué pasa con la 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 lateral: Será Microsoft Sandcastle capaz de enlazar a los archivos de ayuda de. NET Framework o estoy perdiendo el tiempo por referenciando <see cref="T:System.Collections.Generic.ICollection{T}"/>?

Author: m-y, 2011-05-13
Source

3 answers

Tanto Joseph como Ben tocan puntos útiles, pero creo que mi experiencia reciente en castillos de arena 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 doc, si se trata de una referencia a sus propios tipos o a tipos de sistema (y VS respeta sus declaraciones de "uso").

  2. En el escenario de tener un tipo local enmascarar un tipo de sistema, hay dos casos a considerar: su firma califica únicamente su tipo (cubierto por (1) anterior), o su firma duplica exactamente un tipo de sistema. Este último caso requiere una desambiguación explícita calificando completamente el nombre.

  3. Mencionaste el uso de especificar explícitamente el prefijo de tipo de miembro (por ejemplo, "T: SuperWidget"), pero esto es más significativo de lo que la mayoría de la gente cree: si usas un prefijo de tipo de miembro, entonces se requieren nombres cualificados . Esto está documentado en MSDN pero en la letra pequeña muy see ver Procesando el archivo XML. Y para empeorar las cosas, si omites el nombre completo obtendrás ninguna advertencia en el momento de la compilación(!); simplemente no se genera ningún enlace en la representación final del castillo de arena. Hay otros problemas si especifica explícitamente un prefijo de tipo miembro see consulte la sección Desambiguación y resolución de referencias de mi artículo sobre consejos prácticos para Castillos de Arena, Taming Sandcastle: Una Guía para Programadores de.NET para Documentar Su Código.

 16
Author: Michael Sorens,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2017-05-23 12:26:29

No puedo hablar de Sandcastle, pero basado en mi experiencia con otras herramientas, por ejemplo, ReSharper, parece que un tipo necesita ser calificado si a) no está en el alcance o b) está sombreado por otro tipo que está más definido localmente.

En otras palabras, si eres using System.Collections.Generic, entonces no tendrás que calificar ICollection{T}. Sin embargo, si define su propia interfaz ICollection{T} en el mismo archivo, tendrá que calificar la primera (así como la segunda, pensándolo bien).

 3
Author: Ben,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2011-05-13 17:24:01

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

En cuanto a la calificación completa, no es necesario en la mayoría de los escenarios, pero depende de sus usos, como Ben ha mencionado. Siempre y cuando lo que está haciendo referencia está en el alcance (y cualquiera de los dos debe ser, ya que son es probable que lo esté usando si lo está haciendo referencia, o debe agregar el uso para que su código no esté usando el formulario completamente calificado), solo el tipo debería ser suficiente.

 3
Author: Joseph Ferris,
Warning: date(): Invalid date.timezone value 'Europe/Kyiv', we selected the timezone 'UTC' for now. in /var/www/agent_stack/data/www/ajaxhispano.com/template/agent.layouts/content.php on line 61
2017-05-23 10:29:18