visual studio ponen generar estandar documentar documentacion crear como comentarios codigo clases c# generics reference xml-documentation

c# - ponen - generar documentacion visual studio 2017



Cómo hacer referencia a clases y métodos genéricos en documentación xml (7)

TL; DR:

"¿Cómo podría hacer referencia a FancyClass<T> ?"

/// <see cref="FancyClass{T}"/>

"¿Qué pasa con FancyClass<T>.FancyMethod<K>(T value) ?"

/// <see cref="FancyClass{T}.FancyMethod{K}(T)"/>

"¿Cómo puedo hacer referencia a FancyClass<string> ?"

/// <see cref="SomeType.SomeMethod(FancyClass{string})"/> /// <see cref="FancyClass{T}"/> whose generic type argument is <see cref="string"/>

Si bien puede hacer referencia a un método cuya firma incluye FancyClass<string> (por ejemplo, como un tipo de parámetro), no puede hacer referencia directamente a dicho tipo genérico cerrado. El segundo ejemplo funciona alrededor de esa limitación. (Esto se ve, por ejemplo, en la página de referencia de MSDN para el método estático System.String.Concat(IEnumerable<string>) ). :

Reglas de cref comentario de documentación XML:

  • Rodee la lista de parámetros de tipo genérico con llaves {} lugar de con <> escuadras angulares. Esto le evita escapar de este último como &lt; y &gt; - ¡Recuerda, los comentarios de la documentación son XML!

  • Si incluye un prefijo (como T: para tipos, M: para métodos, P: para propiedades, F: para campos), el compilador no realizará ninguna validación de la referencia, sino que simplemente copiará el valor del atributo del cref directamente al documentación salida XML. Por esta razón, deberá usar la sintaxis especial "cadena de ID" que se aplica en dichos archivos: utilice siempre identificadores totalmente calificados y utilice los respaldos para hacer referencia a los parámetros de tipo genéricos ( `n en los tipos, ``n en los métodos) .

  • Si omite el prefijo , se aplican las reglas de denominación de lenguaje habituales: puede descartar espacios de nombres para los que hay una instrucción de using , y puede utilizar palabras clave de tipo de lenguaje como int lugar de System.Int32 . Además, el compilador verificará la corrección de la referencia.

Documentación XML cref cheat sheet:

namespace X { using System; /// <see cref="I1"/> (or <see cref="X.I1"/> from outside X) /// <see cref="T:X.I1"/> interface I1 { /// <see cref="I1.M1(int)"/> (or <see cref="M1(int)"/> from inside I1) /// <see cref="M:X.I1.M1(System.Int32)"/> void M1(int p); /// <see cref="I1.M2{U}(U)"/> /// <see cref="M:X.I1.M2``1(``0)"/> void M2<U>(U p); /// <see cref="I1.M3(Action{string})"/> /// <see cref="M:X.I1.M3(System.Action{System.String})"/> void M3(Action<string> p); } /// <see cref="I2{T}"/> /// <see cref="T:X.I2`1"/> interface I2<T> { /// <see cref="I2{T}.M1(int)"/> /// <see cref="M:X.I2`1.M1(System.Int32)"/> void M1(int p); /// <see cref="I2{T}.M2(T)"/> /// <see cref="M:X.I2`1.M2(`0)"/> void M2(T p); /// <see cref="I2{T}.M3{U}(U)"/> /// <see cref="M:X.I2`1.M3``1(``0)"/> void M3<U>(U p); } }

Al escribir documentación xml puede usar <see cref="something">something</see> , que funciona, por supuesto. ¿Pero cómo hace referencia a una clase o un método con tipos genéricos?

public class FancyClass<T> { public string FancyMethod<K>(T value) { return "something fancy"; } }

Si fuera a escribir documentación xml en alguna parte, ¿cómo haría referencia a la clase de fantasía? ¿Cómo puedo hacer referencia a FancyClass<string> ? ¿Qué hay del método?

Por ejemplo, en una clase diferente, quería que el usuario supiera que devolvería una instancia de FancyClass<int> . ¿Cómo podría hacer una criba para eso?

Más allá de las respuestas de Lasse y TBC:

/// <see cref="T:FancyClass`1{T}"/> for more information. /// <see cref="M:FancyClass`1{T}.FancyMethod`1{K}(T)"/> for more information.

también proporcionará información sobre herramientas correctamente, mientras que su versión lo representa con las llaves.

Ninguna de las respuestas mostradas hasta ahora funciona completamente para mí. ReSharper no convertirá la etiqueta de ver en un enlace Ctrl + clic (por ej. ) a menos que se resuelva por completo.

Si el método en el OP estuviera en un espacio de nombre llamado Test , el enlace completamente resuelto al método mostrado sería:

<see cref="M:Test.FancyClass`1.FancyMethod``1(`0)"/>

Como puede resolver, solo debe haber un backtick antes del número de parámetros de clase, luego dos backticks antes del número de parámetros de tipo de método, luego los parámetros son el parámetro 0 indexado con la cantidad adecuada de backticks.

Así que podemos ver que FancyClass tiene 1 parámetro de tipo de clase, FancyMethod tiene un parámetro de tipo, y un objeto del tipo de parámetro FancyClass se pasará al método.

Como puedes ver más claramente en este ejemplo:

namespace Test { public class FancyClass<A, B> { public void FancyMethod<C, D, E>(A a, B b, C c, D d, E e) { } } }

El enlace se convierte en:

M:Test.FancyClass`2.FancyMethod``3(`0,`1,``0,``1,``2)

O '' Class with 2 type parameters que tiene un method with 3 type parameters donde los parámetros del método son ClassType1 , ClassType2 , MethodType1 , MethodType2 , MethodType3 )

Como nota adicional, no encontré esto documentado en ningún lado y no soy un genio, el compilador me contó todo esto. Todo lo que tiene que hacer es crear un proyecto de prueba, habilitar la documentación XML , luego insertar el código para el que quiere trabajar un enlace y poner el comienzo de un comentario XML en él ( /// ):

namespace Test { public class FancyClass<T> { /// public string FancyMethod<K>(T value) { return "something fancy"; } } public class Test { public static void Main(string[] args) { } } }

Luego construya su proyecto, y la documentación XML emitida incluye el enlace en el elemento doc -> members -> member bajo el name atributo:

<?xml version="1.0"?> <doc> <assembly> <name>Test</name> </assembly> <members> <member name="M:Test.FancyClass`1.FancyMethod``1(`0)"> </member> </members> </doc>

Para hacer referencia al método:

/// <see cref="FancyClass{T}.FancyMethod{K}(T)"/> for more information.

/// <see cref="FancyClass&lt;T>.FancyMethod&lt;K>(T)"/> for more information.

/// Here we discuss the use of <typeparamref name="TYourExcellentType"/>. /// <typeparam name="TYourExcellentType">Your exellent documentation</typeparam>