XML belgeleri yorumları

  • Makale

C# kaynak dosyalarında, bu dosyalarda tanımlanan türler için API belgeleri üreten yapılandırılmış açıklamalar olabilir. C# derleyicisi, yorumları ve API imzalarını temsil eden yapılandırılmış verileri içeren bir XML dosyası oluşturur. Diğer araçlar, örneğin web sayfaları veya PDF dosyaları biçiminde insan tarafından okunabilir belgeler oluşturmak için bu XML çıkışını işlenebilir.

Bu işlem, kodunuza API belgeleri eklemeniz için birçok avantaj sağlar:

  • C# derleyicisi, C# kodunun yapısını açıklama metniyle tek bir XML belgesinde birleştirir.
  • C# derleyicisi, yorumların ilgili etiketler için API imzaları ile eş olduğunu doğrular.
  • XML belge dosyalarını işleme araçları, bu araçlara özgü XML öğelerini ve özniteliklerini tanımlayabilir.

Visual Studio araçları, belge açıklamalarında kullanılan birçok yaygın XML öğesi için IntelliSense sağlar.

Bu makale şu konuları kapsar:

  • Belge yorumları ve XML dosyası oluşturma
  • C# derleyicisi ve derleyicisi tarafından doğrulanmış etiketler Visual Studio
  • Oluşturulan XML dosyasının biçimi

XML belgeleri çıktısı oluşturma

Üçlü eğik çizgiyle gösterilen özel açıklama alanları yazarak kodunuz için belgeler oluşturabilirsiniz. Açıklama alanları, açıklamalarını izleyen kod bloğuna yönelik XML öğeleri içerir. Örnek:

/// <summary>
///  This class performs an important function.
/// </summary>
public class MyClass {}

GenerateDocumentationFile veya DocumentationFile seçeneğini ayarlayın. Derleyici, kaynak kodda XML etiketlerine sahip tüm açıklama alanlarını bulur ve bu açıklamalardan bir XML belge dosyası oluşturun. Bu seçenek etkinleştirildiğinde, derleyici, XML belge açıklamalarına gerek kalmadan projenize bildirilen herkese açık herhangi bir üye için CS1591 uyarısı üretir.

XML açıklama biçimleri

XML belge açıklamalarının kullanımı, belge açıklamalarının nereden başladığını ve sona erer olduğunu belirten sınırlayıcılar gerektirir. XML belge etiketleriyle aşağıdaki sınırlayıcıları kullanırsiniz:

  • /// Tek satırlı sınırlayıcı: Belge örnekleri ve C# proje şablonları bu formu kullanır. Sınırlayıcının ardından boşluk varsa XML çıkışına dahil değildir.

    Not

    Visual Studio ve etiketlerini <summary></summary>/// otomatik olarak ekler ve sınırlayıcıyı kod düzenleyicisine yazdikten sonra imlecinizi bu etiketlerin içine yer alır. Seçenekler iletişim kutusunda bu özelliği açabilirsiniz veya kapatabilirsiniz.

  • /** */ Çok satırlı sınırlayıcılar: /** */ Sınırlayıcılar aşağıdaki biçimlendirme kurallarına sahiptir:

    • Sınırlayıcıyı içeren /** satırda, satırın geri kalanı boşluksa, satır açıklamalar için işlenmez. Sınırlayıcıdan sonra gelen /** ilk karakter boşluk ise, bu boşluk karakteri yoksayılır ve satırın geri kalanı işlenir. Aksi takdirde sınırlayıcıdan sonra satır /** metninin tamamı açıklamanın bir parçası olarak işlenir.

    • Sınırlayıcıyı içeren */ satırda sınırlayıcıya */ kadar yalnızca boşluk varsa bu satır yoksayılır. Aksi takdirde sınırlayıcıya kadar olan satırda */ yer alan metin, açıklamanın bir parçası olarak işlenir.

    • Derleyici, sınırlayıcıyla başlayan /** satırlardan sonra gelen satırlar için her satırın başında ortak bir desene bakarak. Desen isteğe bağlı boşluk ve yıldız işareti ()* ve ardından daha isteğe bağlı boşluktan oluşur. Derleyici her satırın /***/ başında sınırlayıcıyla başlamadan veya sınırlayıcıyla bitemeyen ortak bir desen bulursa, her satır için bu deseni yoksayar.

    • Aşağıdaki açıklamanın işlenen tek bölümü ile başlayan satırdır <summary>. Üç etiket biçimi aynı yorumları üretir.

      /** <summary>text</summary> */

/**
<summary>text</summary>
*/

/**
* <summary>text</summary>
*/

    • Derleyici, ikinci ve üçüncü satırların başında ortak bir " * " deseni tanımlar. Desen çıkışa dahil değildir.

      /**
* <summary>
* text </summary>*/

    • Üçüncü satırda ikinci karakter yıldız işareti olmadığını için derleyici aşağıdaki açıklamada ortak bir desen bulmaz. İkinci ve üçüncü satırlarda yer alan tüm metinler, açıklamanın bir parçası olarak işlenir.

      /**
* <summary>
   text </summary>
*/

    • Derleyici iki nedenle aşağıdaki açıklamada hiçbir desen bulmaz. İlk olarak, yıldız işareti öncesinde boşluk sayısı tutarlı değildir. İkincisi, beşinci satır boşluklarla eşleşmez bir sekmeyle başlar. İki ile beş arasında satırlardan gelen tüm metinler, açıklamanın bir parçası olarak işlenir.

      /**
  * <summary>
  * text
*  text2
 	*  </summary>
*/

XML öğelerine başvurmak için (örneğin, işleviniz XML belge açıklamasında açıklamak istediğiniz belirli XML öğelerini işlemektedir), standart tırnaklama mekanizmasını ( ve )&lt;&gt;kullanabilirsiniz. Kod başvurusu (cref) öğelerinde genel tanımlayıcılara başvurmak için kaçış karakterlerini (örneğin, cref="List&lt;T&gt;") veya küme ayraçlarını () kullanabilirsinizcref="List{T}". Özel bir durum olarak, derleyici, genel tanımlayıcılara başvururken belge açıklamasının yazar için daha az sıkıcı olması için, derleyici tireleri açılı ayraçlar olarak ayrıştırır.

Not

XML belge açıklamaları meta veri değildir; oluşturulan derlemeye dahil edilmezler ve bu nedenle yansıtma üzerinden erişilemezler.

XML belge girişini kabul eden araçlar

Aşağıdaki araçlar XML açıklamalarından çıkış oluşturur:

  • DocFX: DocFX, şu anda C#, Visual Basic ve F# desteğine sahip olan bir .NET API belge oluşturucus tuşuna sahiptir. Ayrıca, oluşturulan başvuru belgelerini özelleştirmenize de olanak sağlar. DocFX, kaynak kodunuz ve Markdown dosyalarından statik bir HTML web sitesi derlemenizi sağlar. Ayrıca DocFX, şablonlar aracılığıyla web sitenizin düzenini ve stilini özelleştirme esnekliği sunar. Özel şablonlar da oluşturabilirsiniz.
  • Sandcastle: Sandcastle araçları, hem kavramsal hem de API başvuru sayfalarını içeren yönetilen sınıf kitaplıkları için yardım dosyaları oluşturur. Sandcastle araçları komut satırı tabanlıdır ve GUI ön uç, proje yönetimi özellikleri veya otomatik derleme işlemi yoktur. Sandcastle Yardım Dosyası Oluşturucusu, otomatik bir şekilde bir yardım dosyası oluşturmak için tek başına GUI ve komut satırı tabanlı araçlar sağlar. Ayrıca Visual Studio bir tümleştirme paketi de kullanılabilir. Böylece, projelerin tamamen farklı bir tümleştirme paketinden oluşturularak Visual Studio.
  • Doxygen: Doxygen , belgelenmiş bir kaynak dosya kümesinden bir satır üzerinde belge tarayıcısı (HTML biçiminde) veya bir off-line başvuru kılavuzu (LaTeX'te) üretir. RTF (MS Word), PostScript, köprü pdf, sıkıştırılmış HTML, DocBook ve Unix man sayfalarında çıkış oluşturma desteği de vardır. Doxygen'i belgelenmemiş kaynak dosyalardan kod yapısını ayıklamak için yapılandırabilirsiniz.

Kimlik dizeleri

Her tür veya üye, çıkış XML dosyasındaki bir öğede depolanır. Bu öğelerin her biri, türü veya üyeyi tanımlayan benzersiz bir kimlik dizesine sahiptir. Kimlik dizesinin işleçleri, parametreleri, dönüş değerlerini, genel tür parametrelerini ref, , ve inparametrelerini hesaba hesabının olması out gerekir. Derleyici, tüm bu olası öğeleri kodlamak için kimlik dizelerini oluşturmak için açıkça tanımlanmış kuralları izler. XML dosyasını işlemeye yönelik programlar, belgelerin geçerli olduğu ilgili .NET meta verilerini veya yansıma öğesini tanımlamak için kimlik dizesini kullanır.

Derleyici, kimlik dizelerini üretirken aşağıdaki kuralları gözlemler:

  • Dizede boşluk yoktur.

  • Dizenin ilk bölümü tek bir karakter ve ardından iki nokta üst üste kullanarak üyenin nasıl olduğunu tanımlar. Aşağıdaki üye türleri kullanılır:

    Karakter Üye türü Notlar
    N ad alanı Belge açıklamalarını bir ad alanına ekamazsınız, ancak desteklenin bulunduğu bu adlara cref başvuruları da ebilirsiniz.
    T tür Tür bir sınıf, arabirim, yapı, enum veya temsilcidir.
    F alan
    P özellik Dizine alınan veya diğer dizinli özellikleri içerir.
    M method Oluşturucular ve işleçler gibi özel yöntemler içerir.
    E event
    ! hata dizesi Dizenin geri kalanı hata hakkında bilgi sağlar. C# derleyicisi, çözümlenemeyen bağlantılar için hata bilgileri oluşturur.

  • Dizenin ikinci bölümü, ad alanının köküden başlayarak öğenin tam nitelikli adıdır. Öğenin adı, kapsayan tür (ler) ve ad alanı noktalarla ayrılır. Öğenin adında nokta varsa, bunlar karma işareti (' # ') ile değiştirilirler. Hiçbir öğenin doğrudan adında bir karma işareti olmadığı varsayılır. Örneğin, dize oluşturucusunun tam adı "System. String. #ctor" dir.

  • Özellikler ve yöntemler için parantez içine alınmış parametre listesi aşağıda verilmiştir. Hiçbir parametre yoksa, hiçbir parantez yok. Parametreler virgülle ayrılır. Her parametrenin kodlaması, bir .NET imzasında nasıl kodlandığını doğrudan izler (aşağıdaki listedeki tüm CAPS öğelerinin tanımları için bkz Microsoft.VisualStudio.CorDebugInterop.CorElementType .):

    • Temel türler. Normal türler ( ELEMENT_TYPE_CLASS veya ELEMENT_TYPE_VALUETYPE ) türün tam nitelikli adı olarak gösterilir.
    • İç türler (örneğin ELEMENT_TYPE_I4ELEMENT_TYPE_TYPEDBYREFELEMENT_TYPE_OBJECTELEMENT_TYPE_STRING ,,,, ve ELEMENT_TYPE_VOID ) karşılık gelen tam türün tam adı olarak gösterilir. Örneğin System.Int32 veya System.TypedReference olabilir.
    • ELEMENT_TYPE_PTR , değiştirilen türden sonra bir ' * ' olarak temsil edilir.
    • ELEMENT_TYPE_BYREF , değiştirilen türden sonra bir ' @ ' olarak temsil edilir.
    • ELEMENT_TYPE_CMOD_OPT , değiştirilen türü takip eden bir '! ' ve değiştirici sınıfının tam adı olarak temsil edilir.
    • ELEMENT_TYPE_SZARRAY dizinin öğe türü takip eden "[]" olarak temsil edilir.
    • ELEMENT_TYPE_ARRAY , virgül sayısının derece-1 olduğu ve bilinen her boyutun alt sınırları ve boyutunun ondalık olarak temsil edildiği [küçükELEMENT_TYPE_ARRAYgöre: size , küçüksize: size ] olarak temsil edilir. Alt sınır veya boyut belirtilmezse, bu atlanır. Belirli bir boyutun alt sınırı ve boyutu atlanırsa, ': ' de atlanır. Örneğin, alt sınır olarak 1 olan iki boyutlu bir dizi ve belirtilmemiş boyutlar [1:, 1:].

  • Yalnızca dönüştürme işleçleri ( op_Implicit ve op_Explicit ) için, yönteminin dönüş değeri, dönüş türü tarafından izlenen olarak ~ kodlanır. Örneğin: <member name="M:System.Decimal.op_Explicit(System.Decimal arg)~System.Int32"> sınıfında bildirildiği System.Decimal atama işlecinin public static explicit operator int (decimal value); etikettir.

  • Genel türler için, türün adının ardından bir geri değer ve ardından genel tür parametrelerinin sayısını belirten bir sayı gelmelidir. Örneğin: <member name="T:SampleClass``2"> olarak public class SampleClass<T, U> tanımlanan bir türün etikettir. Genel tür parametreleri parametre olarak genel türleri alan yöntemler için, genel tür parametreleri birlikte bulunan (örneğin, ' 0, ' 1) sayılar olarak belirtilir. Her sayı, türün genel parametreleri için sıfır tabanlı dizi gösterimini temsil eder.

    • ELEMENT_TYPE_PINNED , değiştirilen türden sonra bir ' ^ ' olarak temsil edilir. C# derleyicisi hiçbir şekilde bu kodlamayı oluşturmaz.
    • ELEMENT_TYPE_CMOD_REQ , değiştirilen türden sonra, değiştirici sınıfının tam adı ve ' | ' olarak temsil edilir. C# derleyicisi hiçbir şekilde bu kodlamayı oluşturmaz.
    • ELEMENT_TYPE_GENERICARRAY dizinin öğe türü takip eden "[?]" olarak temsil edilir. C# derleyicisi hiçbir şekilde bu kodlamayı oluşturmaz.
    • ELEMENT_TYPE_FNPTR "= FUNC: type (ELEMENT_TYPE_FNPTR)" olarak temsil edilir, burada type dönüş türüdür ve type yöntemin bağımsız değişkenlerdir. Bağımsız değişken yoksa, parantezler atlanır. C# derleyicisi hiçbir şekilde bu kodlamayı oluşturmaz.
    • Aşağıdaki imza bileşenleri, aşırı yüklenmiş yöntemleri ayırt etmek için kullanılmadığından gösterilmemektedir:
      • çağırma kuralı
      • dönüş türü
      • ELEMENT_TYPE_SENTINEL

Aşağıdaki örneklerde bir sınıf ve üyeleri için KIMLIK dizelerinin nasıl oluşturulduğu gösterilmektedir:

namespace MyNamespace
{
    /// <summary>
    /// Enter description here for class X.
    /// ID string generated is "T:MyNamespace.MyClass".
    /// </summary>
    public unsafe class MyClass
    {
        /// <summary>
        /// Enter description here for the first constructor.
        /// ID string generated is "M:MyNamespace.MyClass.#ctor".
        /// </summary>
        public MyClass() { }

        /// <summary>
        /// Enter description here for the second constructor.
        /// ID string generated is "M:MyNamespace.MyClass.#ctor(System.Int32)".
        /// </summary>
        /// <param name="i">Describe parameter.</param>
        public MyClass(int i) { }

        /// <summary>
        /// Enter description here for field message.
        /// ID string generated is "F:MyNamespace.MyClass.message".
        /// </summary>
        public string? message;

        /// <summary>
        /// Enter description for constant PI.
        /// ID string generated is "F:MyNamespace.MyClass.PI".
        /// </summary>
        public const double PI = 3.14;

        /// <summary>
        /// Enter description for method func.
        /// ID string generated is "M:MyNamespace.MyClass.func".
        /// </summary>
        /// <returns>Describe return value.</returns>
        public int func() { return 1; }

        /// <summary>
        /// Enter description for method someMethod.
        /// ID string generated is "M:MyNamespace.MyClass.someMethod(System.String,System.Int32@,System.Void*)".
        /// </summary>
        /// <param name="str">Describe parameter.</param>
        /// <param name="num">Describe parameter.</param>
        /// <param name="ptr">Describe parameter.</param>
        /// <returns>Describe return value.</returns>
        public int someMethod(string str, ref int nm, void* ptr) { return 1; }

        /// <summary>
        /// Enter description for method anotherMethod.
        /// ID string generated is "M:MyNamespace.MyClass.anotherMethod(System.Int16[],System.Int32[0:,0:])".
        /// </summary>
        /// <param name="array1">Describe parameter.</param>
        /// <param name="array">Describe parameter.</param>
        /// <returns>Describe return value.</returns>
        public int anotherMethod(short[] array1, int[,] array) { return 0; }

        /// <summary>
        /// Enter description for operator.
        /// ID string generated is "M:MyNamespace.MyClass.op_Addition(MyNamespace.MyClass,MyNamespace.MyClass)".
        /// </summary>
        /// <param name="first">Describe parameter.</param>
        /// <param name="second">Describe parameter.</param>
        /// <returns>Describe return value.</returns>
        public static MyClass operator +(MyClass first, MyClass second) { return first; }

        /// <summary>
        /// Enter description for property.
        /// ID string generated is "P:MyNamespace.MyClass.prop".
        /// </summary>
        public int prop { get { return 1; } set { } }

        /// <summary>
        /// Enter description for event.
        /// ID string generated is "E:MyNamespace.MyClass.OnHappened".
        /// </summary>
        public event Del? OnHappened;

        /// <summary>
        /// Enter description for index.
        /// ID string generated is "P:MyNamespace.MyClass.Item(System.String)".
        /// </summary>
        /// <param name="str">Describe parameter.</param>
        /// <returns></returns>
        public int this[string s] { get { return 1; } }

        /// <summary>
        /// Enter description for class Nested.
        /// ID string generated is "T:MyNamespace.MyClass.Nested".
        /// </summary>
        public class Nested { }

        /// <summary>
        /// Enter description for delegate.
        /// ID string generated is "T:MyNamespace.MyClass.Del".
        /// </summary>
        /// <param name="i">Describe parameter.</param>
        public delegate void Del(int i);

        /// <summary>
        /// Enter description for operator.
        /// ID string generated is "M:MyNamespace.MyClass.op_Explicit(MyNamespace.MyClass)~System.Int32".
        /// </summary>
        /// <param name="myParameter">Describe parameter.</param>
        /// <returns>Describe return value.</returns>
        public static explicit operator int(MyClass myParameter) { return 1; }
    }
}

C# dili belirtimi

Daha fazla bilgi için bkz. belge açıklamaları üzerinde C# dil belirtimi ek.