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

Al escribir documentación xml puedes usar <see cref="something">something</see>, lo cual funciona, por supuesto. Pero, ¿cómo se hace referencia a una clase o 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 elegante? ¿ Cómo puedo hacer referencia a FancyClass<string>? ¿Qué pasa con el 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 algo para ver eso?

Feb 10 '09 19:02 Svish

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 incluya FancyClass<string>(por ejemplo, como un tipo de parámetro), no puede hacer referencia directamente a un tipo genérico cerrado. El segundo ejemplo soluciona 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 ). :

Reglas de comentarios de documentación XML cref:

• Rodee la lista de parámetros de tipo genérico con llaves{} en lugar de <>corchetes angulares. Esto le evita tener que 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 en la salida XML de la documentación. Por este motivo, tendrá que utilizar la sintaxis especial de "cadena de ID" que se aplica a dichos archivos: utilice siempre identificadores completos y utilice comillas invertidas para hacer referencia a parámetros de tipo genéricos ( `nen tipos, ``nen métodos).

• Si omite el prefijo , se aplican las reglas habituales de nomenclatura del idioma: puede eliminar los espacios de nombres para los que hay una usingdeclaración y puede utilizar las palabras clave de tipo del idioma, como inten lugar de System.Int32. Además, el compilador verificará que la referencia sea correcta.

crefHoja de referencia de comentarios de documentación XML :

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

Dec 18 '2016 12:12 stakx - no longer contributing

/// <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.

Feb 10 '2009 12:02 thinkbeforecoding