Cómo hacer referencia a clases y métodos generics en documentación xml

Al escribir documentación xml puede usar something , que funciona, por supuesto. ¿Pero cómo hace referencia a una clase o un método con tipos generics?

 public class FancyClass { public string FancyMethod(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 ? ¿Qué hay del método?

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

    Para hacer referencia al método:

     ///  for more information. 
     /// Uses a  instance. 

    Por cierto, estaba presente en la documentación de .NET Framework 2.0 y 3.0 de MSDN, pero desapareció en la versión 3.5

    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. imagen aquí ) 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:

    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 { public void FancyMethod(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 comstackdor 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 { /// public string FancyMethod(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"?>   Test       

    TL; DR:

    “¿Cómo podría hacer referencia a FancyClass ?”

      ///  

    “¿Qué pasa con FancyClass.FancyMethod(T value) ?”

      ///  

    “¿Cómo puedo hacer referencia a FancyClass ?”

      ///  ///  whose generic type argument is  

    Si bien puede hacer referencia a un método cuya firma incluye FancyClass (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) ). :

    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 < y > – ¡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 comstackdor 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 syntax 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 generics ( `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 comstackdor verificará la corrección de la referencia.

    Documentación XML cref cheat sheet:

     namespace X { using System; ///  (or  from outside X) ///  interface I1 { ///  (or  from inside I1) ///  void M1(int p); ///  ///  void M2(U p); ///  ///  void M3(Action p); } ///  ///  interface I2 { ///  ///  void M1(int p); ///  ///  void M2(T p); ///  ///  void M3(U p); } } 

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

     ///  for more information. ///  for more information. 

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

     /// Here we discuss the use of . /// Your exellent documentation 
     ///  for more information.