XML belgelerinde genel sınıflara ve yöntemlere başvurma


198

Xml belgelerini yazarken <see cref="something">something</see>elbette işe yarar . Peki genel sınıfa sahip bir sınıfa veya yönteme nasıl başvuruyorsunuz?

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

Bir yere xml belgeleri yazacak olsaydım, fantezi sınıfına nasıl başvururum? a'ya nasıl başvurabilirim FancyClass<string>? Yöntem ne olacak?

Örneğin farklı bir sınıfta kullanıcıya bir örneğini döndüreceğimi bildirmek istedim FancyClass<int>. Bunun için nasıl bir cref şeyi yapabilirim?

Yanıtlar:


258

Yönteme başvurmak için:

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

3
Bu cevap için teşekkürler! Aslında
MSDN'nin

6
Aslında VS2010 araç ipuçlarında da işe yaradığına inanıyorum, örneğin "FancyClass 1{T}.FancyMethod1 {K} (T)" gibi genel argümanların sayısını belirtmelisiniz
Stephen Drew

Bununla ilgili ne demek istediğinden emin değilim. Bunları hiç eklemek zorunda kalmadım ve her zaman benim için çalıştı. İşe yaramayacağı belirli bir örneğiniz var mı? Eğer öyleyse, lütfen bir yere gönderin (hatta kendinize bir cevap verin.)
Lasse V. Karlsen

@Lasse, lütfen Steve'in cevabına ve yorumlarına bakınız. Yanıtınız doğru Intellisense araç ipuçlarını kapsamıyor.
Jakub Januszkiewicz

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

BTW, .Net Framework 2.0 ve 3.0'ın MSDN belgelerinde mevcuttu , ancak 3.5 sürümünde hayal kırıklığına uğradı


4
spesifik bir T örneği ne olacak? dize gibi mi? Belki mümkün değil?
Svish

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

Örneğin bir yöntem yalnızca <string> Listesini döndürürse. Ama önemli değil :)
Svish

7
Evet ben de merak ediyordum ... FancyClass {string} 'i yazarken dalgalı çizgiler paylaşıyor ama FancyClass {String} yazarken değil ...
thinkbeforecoding

6
"Kodlamadan önce düşün" tarafından yukarıdaki gözlem nedeni, c # diğer adları ile çalışmaz olmasıdır. Örneğin kullanımına ihtiyaç Int32yerine int, Singleyerine floatvb (bu konuda dava başkasının tökezlemeleri burada bu bilgiyi koymak)
AnorZaken

27

TL; DR:

"Nasıl başvurabilirim FancyClass<T>?"

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

"Ne olmuş FancyClass<T>.FancyMethod<K>(T value)?"

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

"A'ya nasıl başvurabilirim FancyClass<string>?"

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

Eğer iken can kimin imzası içeren bir yöntem başvuru FancyClass<string>(örneğin bir parametre türü gibi), sen olamaz böyle bir doğrudan genel tür kapalı referans. İkinci örnek bu sınırlama etrafında gider. (Bu, örneğin statik System.String.Concat(IEnumerable<string>)yöntemin MSDN refence sayfasında görülür ). :

XML dokümantasyon yorum crefkuralları:

  • Genel tip parametre listesini kıvırcık parantez içine alın {}<> köşeli yerine içine alın. Bu sizi ikincisinden kaçmaktan kurtarır &lt;ve &gt;hatırlayın, dokümantasyon yorumları XML'dir!

  • Bir önek eklerseniz (T: türler M:için, yöntemler P:için, özellikler F:için, alanlar için), derleyici başvurunun herhangi bir doğrulamasını gerçekleştirmez, ancakcref öznitelik değerini doğrudan belge XML çıktısına . Bu nedenle, bu tür dosyalar için geçerli olan özel "ID dizesi" sözdizimini kullanmanız gerekir: her zaman tam nitelikli tanımlayıcılar kullanın ve genel tür parametrelerine ( `ntürlerde, ``nyöntemlerde) başvurmak için geri işaretlerini kullanın .

  • Öneki atlarsanız , normal dil adlandırma kuralları geçerlidir: usingifadesi olan ad alanlarını bırakabilir ve intbunun yerine dilin tür anahtar kelimelerini kullanabilirsiniz System.Int32. Ayrıca, derleyici referansın doğruluğunu kontrol edecektir.

XML belgeleri yorum crefhile sayfası:

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

Sadece Tkısmı nasıl ifade edilir ?
nawfal

4
<typeparamref name="T"/>
Anladım

21

Şimdiye kadar gösterilen cevapların hiçbiri benim için tamamen işe yaramıyor. ReSharper see etiketi Ctrl+ tıklanabilir bir bağlantıya dönüştürmez (ör.burada resim tam olarak çözümlenmedikçe ) .

OP'deki yöntem adı verilen bir ad alanında Testolsaydı, gösterilen yönteme tamamen çözümlenmiş bağlantı şöyle olurdu:

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

Çalışabileceğiniz gibi, sınıf tipi parametre sayısından önce yalnızca bir backtick, daha sonra yöntem türü parametre sayısından önce iki backtick olmalı, sonra parametreler uygun sayıda backtick ile sıfır indeksli parametredir.

Bu nedenle FancyClass, bir sınıf tipi parametresinin, FancyMethodbir tür parametresinin olduğunu ve FancyClassparametre türünde bir nesnenin yönteme aktarılacağını görebiliriz.

Bu örnekte daha net 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ı şöyle olur:

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

Ya da "üç tip parametrelerle bir yöntem vardır iki tip parametrelerle Sınıf yöntemi parametrelerdir nerede ClassType1, ClassType2, MethodType1, MethodType2, MethodType3"


Ek bir not olarak, bunu hiçbir yerde belgeledim ve bir dahi değilim, derleyici bana tüm bunları söyledi. Tek yapmanız gereken bir test projesi oluşturmak, XML dokümantasyonunu etkinleştirmek , daha sonra bir bağlantı oluşturmak istediğiniz kodu eklemek ve üzerine bir XML dokümanı yorumunun başlangıcını koymaktır ( ///):

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 projenizi oluşturun ve çıktı XML belgelerinde öznitelik altında doc-> members-> memberöğesindeki bağlantı içerir name:

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

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

3
Bu, özellikle deneme yanılma sürecinden geçmeden doğru gösterimi bulma hilesi nedeniyle daha fazla oy almalıdır. Kudos my man
Peter

10

Lasse ve TBC'nin cevaplarından başka:

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

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

aynı zamanda araç ipuçlarını doğru bir şekilde sunarken, sürümleri kıvırcık parantezlerle işler.


2
Kullanılması cref = "System.Collections.Generic.List bkz < 1{T}"/>** causes a build-time warning: **XML comment on 'Blah' has syntactically incorrect cref attribute 'System.Collections.Generic.List> 1 <T Eğer kimse bu nasıl kullanmaları gerektiğini üzerinde durmak için bakım ediyorum? -
Jakub Januszkiewicz

2
Merhaba Jakub, Bu gerçekten işe yaramıyor. Araç ipuçlarını doğru şekilde çalıştırabilmemin tek yolu <see cref = "T: <fullTypeName>` 1 {T} "/>.
Stephen Drew

2
Tamam, kısmen anladım. Yöntemin kendisi genel değilse (<T> .Add () Listesinde olduğu gibi), bu işe yarar: <bkz. Cref = "M: System.Collections.Generic.List`1 {T} .Add (T)" /> .
Jakub Januszkiewicz

1
Benim için çalışmıyor gibi görünüyor. Ben yazdım (bir ArrayList bir liste <T> dönüştürür) yorum başlığında <see cref = "M: System.Collections.Generic.List`1 {T}" /> var ama ReSharper işaretler sözdizimi hatası olarak gösterilir ve IntelliSense yalnızca sözlü olarak görüntüler. VS 2010 / R # 6.1.37.86
Mike Loux

8
Aha! Çalışmak için <see cref = "T: System.Collections.Generic.List`1" /> "alabildim . Kıvırcık parantez yerine T: kullanmak hile yaptı. Tam ad alanını genişletiyor, ve ad alanını eklemezseniz hile çalışmaz, bu yüzden mükemmel değildir, ancak işe yarayacaktır
Mike Loux

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

3
Diğer cevapların genel bir sınıfa nasıl başvurulacağını kapsadığını, bu cevabın type parametresini kendi başımıza nasıl başvuracağımı gösterdiğini ve bu da yapmak istediğim şey olduğunu gösterdi.
jrh

1
/// <see cref="FancyClass&lt;T>.FancyMethod&lt;K>(T)"/> for more information.
Sitemizi kullandığınızda şunları okuyup anladığınızı kabul etmiş olursunuz: Çerez Politikası ve Gizlilik Politikası.
Licensed under cc by-sa 3.0 with attribution required.