Al escribir documentación xml puede usar <see cref="something">something</see>, lo 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 iba a escribir documentación xml en alguna parte, ¿cómo haría referencia a la clase elegante? ¿Cómo puedo hacer referencia a un FancyClass<string>? ¿Qué hay del método?

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

Para hacer referencia al método:

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

/// <summary>Uses a <see cref="FancyClass{T}" /> instance.</summary>

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

TL; DR:

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

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

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

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

"¿Cómo puedo hacer referencia a un 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 referencia a un tipo genérico cerrado directamente. El segundo ejemplo funciona alrededor de esa limitación. (Esto se ve, por ejemplo, en la página de referencia de MSDN para el System.String.Concat(IEnumerable<string>)método estático ). :

Comentario de documentación XML crefReglas de :

• Rodee la lista de parámetros de tipo genérico con llaves en{} lugar de con<> llaves angulares. Esto le evita escapar de esto último, <y >recuerde, ¡los comentarios de la documentación son XML!

• Si incluye un prefijo (comoT: para tipos, M:métodos, P:propiedades, F:campos), el compilador no realizará ninguna validación de la referencia, sino que simplemente copiará el crefvalor del atributo directamente a la salida XML de la documentación. Por esta razón, tendrá que usar la sintaxis especial de "cadena de ID" que se aplica en dichos archivos: use siempre identificadores totalmente calificados y use las teclas de retroceso para hacer referencia a parámetros de tipo genérico ( `nen tipos, ``nen métodos).

• Si omite el prefijo , se aplicarán las reglas de nomenclatura de idiomas habituales: puede colocar espacios de nombres para los que hay unusing declaración y puede usar las palabras clave de tipo de idioma como en intlugar de System.Int32. Además, el compilador verificará que la referencia sea correcta.

Documentación XML comentario crefhoja de trucos:

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);
    }
}

Ninguna de las respuestas mostradas hasta ahora funciona completamente para mí. ReSharper no convertirá la etiqueta ver en un Ctrlenlace que pueda hacer clic con un clic (p. Ej. ) a menos que se resuelva por completo.

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

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

Como es posible que pueda resolver, solo debe haber un retroceso antes del número de parámetros de tipo de clase, luego dos retrocesos antes del número de parámetros de tipo de método, luego los parámetros son el parámetro indexado a cero con el número apropiado de retrocesos.

Entonces podemos ver que FancyClasstiene un parámetro de tipo de clase, FancyMethodtiene un parámetro de tipo y un objeto deFancyClass parámetro de tipo y se pasará tipo de parámetro al método.

Como puede 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 "Clase con dos parámetros de tipo, que tiene un método con tres parámetros de tipo, donde los parámetros del método son ClassType1, ClassType2, MethodType1, MethodType2,MethodType3 "

Como nota adicional, no encontré esto documentado en ninguna parte 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 desea elaborar un enlace y poner el comienzo de un comentario de documento 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 resultante incluye el enlace en el elemento doc-> members-> memberdebajo del atributo name:

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

        </member>
    </members>
</doc>

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.

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

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