Ao escrever a documentação xml, você pode usar <see cref="something">something</see>, o que funciona, é claro. Mas como você faz referência a uma classe ou a um método com tipos genéricos?

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

Se eu fosse escrever uma documentação xml em algum lugar, como referenciaria a classe sofisticada? como posso fazer referência a FancyClass<string>? E o método?

Por exemplo, em uma classe diferente, eu queria informar ao usuário que retornarei uma instância de FancyClass<int>. Como eu poderia fazer uma coisa de ver cref por isso?

Para referenciar o método:

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

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

BTW, ele estava presente na documentação do MSDN do .Net Framework 2.0 e 3.0 , mas desapareceu na versão 3.5

TL; DR:

"Como eu faria referência FancyClass<T>?"

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

"Sobre o quê FancyClass<T>.FancyMethod<K>(T value)?"

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

"Como posso referenciar a FancyClass<string>?"

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

Embora você possa fazer referência a um método cuja assinatura inclua FancyClass<string>(por exemplo, como um tipo de parâmetro), não é possível fazer referência diretamente a um tipo genérico fechado. O segundo exemplo contorna essa limitação. (Isso é visto, por exemplo, na página de referênciaSystem.String.Concat(IEnumerable<string>) do MSDN para o método estático ). :

crefRegras de comentários da documentação XML :

• Coloque a lista de parâmetros de tipo genérico entre chaves, em{} vez de entre <>colchetes. Isso evita que você escape deste último <e >lembre-se de que os comentários da documentação são XML!

• Se você incluir um prefixo (comoT: para tipos, M:métodos, P:propriedades, F:campos), o compilador não executará nenhuma validação da referência, mas simplesmente copiará o crefvalor do atributo diretamente para a saída XML da documentação. Por esse motivo, você precisará usar a sintaxe especial "ID string" que se aplica a esses arquivos: sempre use identificadores totalmente qualificados e use backticks para referenciar parâmetros de tipo genérico ( `nem tipos, ``nem métodos).

• Se você omitir o prefixo , aplicar-se-ão regras regulares de nomeação de idiomas: você pode eliminar os namespaces para os quais há umusing instrução e pode usar as palavras-chave do tipo de idioma, como em intvez de System.Int32. Além disso, o compilador irá verificar a referência para correção.

crefFolha de dicas sobre comentários da documentação 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);
    }
}

Nenhuma das respostas mostradas até agora funciona completamente para mim. O ReSharper não converterá a tag see em um Ctrllink com + clique (por exemplo ), a menos que seja completamente resolvida.

Se o método no OP estivesse em um namespace chamado Test, o link completamente resolvido para o método mostrado seria:

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

Como você pode resolver, deve haver apenas um backtick antes do número de parâmetros do tipo de classe, depois dois backticks antes do número de parâmetros do tipo de método e, em seguida, os parâmetros são o parâmetro indexado a zero com o número apropriado de backticks.

Portanto, podemos ver que FancyClasspossui um parâmetro de tipo de classe, FancyMethodtem um parâmetro de tipo e um objeto do FancyClasstipo de parâmetro será passado para o método

Como você pode ver mais claramente neste exemplo:

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

O link se torna:

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

Ou "Classe com dois parâmetros de tipo que tem um método com três parâmetros do tipo em que os parâmetros do método são ClassType1, ClassType2, MethodType1, MethodType2,MethodType3 "

Como uma observação adicional, não encontrei isso documentado em nenhum lugar e não sou um gênio, o compilador me contou tudo isso. Tudo o que você precisa fazer é criar um projeto de teste, ativar a documentação XML , inserir o código para o qual deseja criar um link e colocar o início de um comentário de documento XML ( ///):

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

    public class Test
    {
        public static void Main(string[] args) { }
    }
}

Em seguida, construa seu projeto e a documentação XML gerada inclui o link no elemento doc-> members-> membersob o 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>

Além das respostas de Lasse e TBC:

/// <see cref="T:FancyClass`1{T}"/> for more information.

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

também fornecerá dicas de ferramenta corretamente, enquanto sua versão a renderiza com chaves.

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