Saat menulis dokumentasi xml dapat Anda gunakan <see cref="something">something</see>, yang tentu saja berfungsi. Tetapi bagaimana Anda merujuk kelas atau metode dengan tipe generik?

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

Jika saya akan menulis dokumentasi xml di suatu tempat, bagaimana saya mereferensikan kelas mewah? bagaimana saya bisa referensi FancyClass<string>? Bagaimana dengan metodenya?

Sebagai contoh di kelas yang berbeda saya ingin memberi tahu pengguna bahwa saya akan mengembalikan instance FancyClass<int>. Bagaimana saya bisa membuat benda yang terlihat untuk itu?

Untuk referensi metode:

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

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

BTW, itu hadir dalam dokumentasi MSDN .Net Framework 2.0 dan 3.0 , tetapi menghilang dalam versi 3.5

TL; DR:

"Bagaimana saya referensi FancyClass<T>?"

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

"Bagaimana dengan FancyClass<T>.FancyMethod<K>(T value)?"

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

"Bagaimana saya bisa referensi a FancyClass<string>?"

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

Meskipun Anda dapat mereferensikan metode yang tanda tangannya termasuk FancyClass<string>(misalnya sebagai tipe parameter), Anda tidak dapat mereferensikan tipe generik tertutup secara langsung. Contoh kedua mengatasi batasan itu. (Ini terlihat misalnya pada halaman referensi MSDN untuk System.String.Concat(IEnumerable<string>)metode statis ). :

crefAturan komentar dokumentasi XML :

• Kelilingi daftar parameter tipe umum dengan kurung kurawal{} alih-alih dengan <>kurung sudut. Ini membuat Anda terhindar dari yang terakhir <dan >- ingat, komentar dokumentasi adalah XML!

• Jika Anda menyertakan awalan (sepertiT: untuk tipe, M:untuk metode, P:untuk properti, F:untuk bidang), kompiler tidak akan melakukan validasi referensi, tetapi cukup salin nilai crefatribut langsung ke output XML dokumentasi. Untuk alasan ini, Anda harus menggunakan sintaks "string ID" khusus yang berlaku dalam file tersebut: selalu gunakan pengidentifikasi yang sepenuhnya memenuhi syarat, dan gunakan backtick untuk referensi parameter tipe umum ( `npada tipe, ``npada metode).

• Jika Anda menghilangkan awalan , aturan penamaan bahasa biasa berlaku: Anda dapat menjatuhkan ruang nama yang berisi usingpernyataan, dan Anda dapat menggunakan kata kunci jenis bahasa seperti intbukan System.Int32. Juga, kompiler akan memeriksa referensi untuk kebenaran.

crefLembar contekan komentar dokumentasi 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);
    }
}

Tidak ada jawaban yang ditunjukkan sejauh ini yang berfungsi sepenuhnya untuk saya. ReSharper tidak akan mengonversi tag lihat menjadi Ctrltautan + klik-bisa (mis. ) Kecuali itu sepenuhnya diselesaikan.

Jika metode dalam OP berada dalam namespace yang disebut Test, tautan yang sepenuhnya terselesaikan ke metode yang ditampilkan adalah:

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

Karena Anda mungkin dapat bekerja, seharusnya hanya ada satu backtick sebelum jumlah parameter tipe kelas, kemudian dua backtick sebelum jumlah parameter tipe metode, maka parameternya adalah parameter indeks-nol dengan jumlah backticks yang sesuai.

Jadi kita dapat melihat bahwa FancyClassmemiliki satu parameter tipe kelas, FancyMethodmemiliki satu tipe parameter, dan objek FancyClasstipe parameter akan diteruskan ke metode.

Seperti yang dapat Anda lihat dengan lebih jelas dalam contoh ini:

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

Tautan menjadi:

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

Atau "Kelas dengan dua jenis parameter yang memiliki metode dengan tiga parameter jenis di mana parameter metode yang ClassType1, ClassType2, MethodType1, MethodType2, MethodType3"

Sebagai catatan tambahan, saya tidak menemukan ini didokumentasikan di mana pun dan saya bukan jenius, kompiler mengatakan kepada saya semua ini. Yang harus Anda lakukan adalah membuat proyek pengujian, mengaktifkan dokumentasi XML , lalu menyisipkan kode yang ingin Anda buat tautannya, dan menuliskan komentar dokumen XML di atasnya ( ///):

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

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

Kemudian buat proyek Anda, dan dokumentasi XML yang dihasilkan menyertakan tautan dalam elemen doc-> members-> di memberbawah atribut name:

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

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

Lebih jauh dari jawaban oleh Lasse dan TBC:

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

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

juga akan memberikan tooltips dengan benar, sedangkan versi mereka membuatnya dengan kurung kurawal.

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