2009-02-10 20 views
163

xml belgeleri yazarken, elbette çalışan <see cref="something">something</see> kullanabilirsiniz. Peki, genel bir sınıfla bir sınıfa veya yönteme nasıl başvurursunuz?xml belgelerinde genel sınıflar ve yöntemlere başvurma

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

Bir yerde xml belgeleri yazacak olsaydım, fantezi sınıfına nasıl başvururdum? Bir FancyClass<string>'a nasıl başvurabilirim? Yöntemden ne haber?

Örneğin, farklı bir sınıfta, kullanıcının bir örneği FancyClass<int> döndüreceğimi bilmesini istedim. Bunun için nasıl bir şey görebildim?

+0

(bu 7 yaşındaki soruya cevabım için aşağı kaydırın.) – JohnL4

cevap

220

içinde disapeared: Lasse göre cevaplardan daha

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

teşekkür (bu konuda dava başkasının tökezlemeleri burada bu bilgiyi koymak)! Aslında tarihinde MSDN'ın sayfasından eksik: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx – joce

+5

VS2010 Eğer jenerik argümanların sayısını belirtmek gerekir tooltips içinde de çalışmak için ben aslında inanıyorum Örneğin "FancyClass'1 {T} .FancyMethod'1 {K} (T)" –

+0

Bunun hakkında ne kastettiğinizden emin değilsiniz. Bunları eklemek zorunda kalmamıştım ve her zaman benim için çalıştı. Çalışılmadığı özel bir örneğiniz var mı? Eğer öyleyse, lütfen bir yere gönderin (veya kendinize bir cevap verin.) –

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

btw, bu .Net Framework 2.0 ve 3.0 MSDN belgelerinde mevcuttu, ancak yöntemi başvurmak için version 3.5

+2

neyi T spesifik bir örneği olacak? string gibi mi? Belki mümkün değil mi? – Svish

+0

ne demek istiyorsun? Belirli bir sürümü bildiremezsiniz, bu yüzden ona da başvuramazsınız. –

+0

Örneğin bir yöntem, örneğin yalnızca Listesini döndürür. FancyClass {dize} yazarken FancyClass {dize} ... – Svish

9

ve TBC:

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

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

ayrıca araç ipuçlarını doğru bir şekilde sunarken, onların versiyonu da kaşlı ayraçlarla birlikte sunacaktır. gösterilen cevapların

+1

kullanma ** ** neden olan bir yapı zamanlı uyarı: ** 'Filan' XML açıklama sözdizimi yanlış cref özelliği 'ni System.Collections vardır .Generic.List'1 ** - bunu nasıl kullanması gerektiğine dikkat etmek ister misiniz? –

+2

Merhaba Jakub, Bu gerçekten işe yaramıyor. Araç ipuçlarını düzgün çalışabilmem için tek yol . –

+0

teşekkürler, tüm işler şimdi doğru şekilde çalışıyor. Hem T: hem de açık (ve doğru!) Jenerik parametrelerin sayısı, uyarılar olmadan ve doğru Intellisense araç ipuçlarına sahip olmak için gereklidir. Lütfen cevabınızı güncelleyin, bunu en çok sevdiğimden mutluluk duyarım. BTW, dokümantasyonun HTML/neyse ne şekilde derlendiğini görünce henüz görmedim. –

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

Yok şimdiye kadar benim için tamamen çalışır. ReSharper, tamamıyla çözülmediği sürece, bkz: etiketini Ctrl + tıklanabilir bir bağlantıya (ör. image here) dönüştürmez. OP yöntem Test adında bir ad alanında olsaydı

, gösterilen yönteme tamamen çözülmüş bağlantı olacaktır:

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

atlatmanın mümkün olabilir gibi, sadece olmalı sınıf tipi parametrelerinin sayısından önce bir backtick, daha sonra metot tipi parametrelerinin sayısından önce iki backtick, daha sonra parametreler uygun sayıda backtick'e sahip 0-endeksli parametredir.

Bu yüzden, FancyClass'ın 1 sınıf tipi parametresi olduğunu, FancyMethod'un bir tür parametresi olduğunu ve FancyClass parametre türünün bir nesnesinin yönteme geçirileceğini görebiliriz.

daha net bu örnekte görebileceğiniz gibi:

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

bağlantı haline gelir:

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

Ya yöntem parametreleri ClassType1, ClassType2 olan bir method with 3 type parameters bulunur Class with 2 type parameters, MethodType1, MethodType2, MethodType3)


Ek bir not olarak, bu belgeyi hiçbir yerde bulamadım ve ben bir dahi değilim, derleyici bana tüm bunları anlattı.

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

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

Sonra oluşturursunuz: Tüm yapmanız gereken (///) o zaman için bir bağlantı Egzersiz yapmak isteyen kodu eklemek, bir test projesi, enable XML documentation oluşturmak ve üzerine bir XML doc yorum satırını koymak olduğunu >members - - Projeniz, çıktılanmasını XML belgeleri doc bu bağlantıyı bulunduran özniteliği name altında>member elemanı:

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

     </member> 
    </members> 
</doc> 
+2

Bu, özellikle doğru notasyonu bulmak için hile nedeniyle daha fazla upvotes almalıyım deneme yanılma yoluyla git. – Peter

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

TL; DR:

"FancyClass<T> nasıl başvuruda bulunabilirim?"

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

"Ne FancyClass<T>.FancyMethod<K>(T value) ne olacak?"

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

"Nasıl bir FancyClass<string> başvurabilir?"
/// <see cref="SomeType.SomeMethod(FancyClass{string})"/> 
    /// <see cref="FancyClass{T}"/> whose generic type argument is <see cref="string"/> 

Eğer olabilir referans olan imza (örneğin, bir parametre türü gibi) FancyClass<string> içeren bir yöntem olsa da, olamaz referans bu tür bir kapalı genel tür şirketinden. İkinci örnek bu sınırlama etrafında çalışır. (Bu, örn., MSDN refence page for the static System.String.Concat(IEnumerable<string>) method'da görülür). :

XML belgelerine yorum cref kuralları:

  • Surround küme parantezleri {} yerine <> köşeli parantez içeren bir ile genel tür parametre listesi. Bu, ikincisi &lt; ve &gt; — olarak kaçmaktan kurtarır, dökümanların yorumları XML!

  • Eğer bir önek eklerseniz, derleyici referans herhangi doğrulama gerçekleştirmek, ama sadece cref özellik değerini kopyalamak olmaz (türleri, yöntemleri için M:, özellikleri için P:, alanlar için F: için gibi T:) belgelerin XML çıkışına doğrudan. Bu nedenle, bu tür dosyalar için geçerli olan özel "ID string" syntax'u kullanmanız gerekir: her zaman tam nitelikli tanımlayıcılar kullanın ve genel tip parametrelerini referans almak için backticks kullanın (yöntemler üzerinde `n, yöntemlerde ``n). Eğer önek atlarsanız

  • , düzenli dil adlandırma kuralları geçerlidir: Bir using deyim var olan ad alanlarını bırakın ve bu tür int yerine System.Int32 olarak dilin tip anahtar kelimeler kullanabilirsiniz. Ayrıca, derleyici referans için doğruluğu kontrol edecektir.

XML belgelerine yorum cref kısa notlara:

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); 
    } 
} 
İlgili konular