Aracılığıyla paylaş

XML API belge açıklamaları oluşturma

C# kaynak dosyaları, bu dosyalarda tanımlanan türler için API belgeleri oluşturan yapılandırılmış açıklamalar içerebilir. C# derleyicisi, açıklamaları ve API imzalarını temsil eden yapılandırılmış veriler 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 çıktısını işleyebilir.

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

  • C# derleyicisi, C# kodunun yapısını açıklamaların metniyle tek bir XML belgesinde birleştirir.
  • C# derleyicisi, açıklamaların ilgili etiketler için API imzalarıyla eşleşdiğini doğrular.
  • XML belge dosyalarını işleyen araçlar, bu araçlara özgü XML öğelerini ve özniteliklerini tanımlayabilir.

Visual Studio gibi 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 açıklamaları ve XML dosyası oluşturma
  • C# derleyicisi ve Visual Studio tarafından doğrulanan etiketler
  • Oluşturulan XML dosyasının biçimi

XML belge çıkışı oluşturma

Üç eğik çizgiyle gösterilen özel açıklama alanları yazarak kodunuz için belgeler oluşturursunuz. Açıklama alanları, açıklamaları izleyen kod bloğunu açıklayan XML öğelerini içerir. Örneğin:

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

GenerateDocumentationFile veya DocumentationFile seçeneğini ayarlarsınız ve derleyici kaynak kodda XML etiketleri olan tüm açıklama alanlarını bulur ve bu açıklamalardan bir XML belge dosyası oluşturur. Bu seçenek etkinleştirildiğinde, derleyici projenizde XML belge açıklamaları olmadan bildirilen genel olarak görünür herhangi bir üye için CS1591 uyarısını oluşturur.

XML açıklama biçimleri

XML belge açıklamalarının kullanılması, belge açıklamasının nerede başladığını ve bittiğini belirten sınırlayıcılar gerektirir. XML belge etiketleriyle aşağıdaki sınırlayıcıları kullanırsınız:

  • /// Tek satırlı sınırlayıcı: Belge örnekleri ve C# proje şablonları bu formu kullanır. Boşluk sınırlayıcıyı izlerse, XML çıkışına dahil değildir.

    Uyarı

    Visual Studio, ve </summary> etiketlerini otomatik olarak ekler ve siz sınırlayıcıyı <summary> kod düzenleyicisine yazdıktan sonra imlecinizi bu etiketlerin /// içine yerleştirir. Seçenekler iletişim kutusunda bu özelliği açabilir 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 /** sonraki ilk karakter boşluksa, bu boşluk karakteri yoksayılır ve satırın geri kalanı işlenir. Aksi takdirde, sınırlayıcıdan sonraki satırın /** tüm metni 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ırdaki */ metin açıklamanın bir parçası olarak işlenir.

    • Sınırlayıcı ile /** başlayan satırdan sonraki satırlar için, derleyici her satırın başında ortak bir desen arar. Desen, isteğe bağlı boşluk ve/veya yıldız işareti ()* ve ardından daha fazla isteğe bağlı boşluk içerebilir. Derleyici, her satırın başında sınırlayıcıyla başlamayan veya sınırlayıcıyla /***/ biten 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 <summary>başlayan satırdır. Üç etiket biçimi aynı açıklamaları oluşturur.

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

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

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

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

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

    • Üçüncü satırdaki ikinci karakter yıldız olmadığından derleyici aşağıdaki açıklamada ortak bir desen bulmaz. İkinci ve üçüncü satırlardaki tüm metinler açıklamanın bir parçası olarak işlenir.

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

    • Derleyici, aşağıdaki açıklamada iki nedenden dolayı desen bulmaz. İlk olarak, yıldız işaretinden önceki boşluk sayısı tutarlı değildir. İkincisi, beşinci satır boşluklarla eşleşmeyen bir sekmeyle başlar. İki ile beş arasında satırdaki 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 bir XML belge açıklamasında açıklamak istediğiniz belirli XML öğelerini işler), standart alıntılama mekanizmasını (&lt; ve &gt;) kullanabilirsiniz. Kod başvurusu (cref) öğelerindeki genel tanımlayıcılara başvurmak için kaçış karakterlerini (örneğin, cref="List&lt;T&gt;") veya ayraçları (cref="List{T}") kullanabilirsiniz. Özel bir durum olarak, derleyici genel tanımlayıcılara başvururken belge açıklamasını yazara daha az hantal hale getirmek için ayraçları açılı ayraç olarak ayrıştırır.

Uyarı

Tek satırlık XML açıklama sınırlayıcısını ///kullanarak açıklamalar yazarsanız, ancak hiçbir etiket içermiyorsanız, derleyici bu açıklamaların metnini XML çıkış dosyasına ekler. Ancak, çıktı gibi <summary>XML öğelerini içermez. XML açıklamalarını kullanan araçların çoğu (Visual Studio IntelliSense dahil) bu açıklamaları okumaz.

XML belgeleri 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# destekleyen .NET için bir API belge oluşturucusdur. Ayrıca, oluşturulan başvuru belgelerini özelleştirmenize de olanak tanır. DocFX, kaynak kodunuz ve Markdown dosyalarınızdan statik bir HTML web sitesi oluşturur. DocFX ayrıca şablonlar aracılığıyla web sitenizin düzenini ve stilini özelleştirme esnekliği sağlar. Ö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 ucu, proje yönetimi özellikleri veya otomatik derleme işlemi içermez. 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. Bunun için bir Visual Studio tümleştirme paketi de sağlanır, böylece proje oluşturma ve tamamen Visual Studio'dan yönetilebilir.
  • Doxygen: Doxygen , belgelenmiş bir kaynak dosya kümesinden çevrimiçi bir belge tarayıcısı (HTML olarak) veya çevrimdışı başvuru kılavuzu (LaTeX'te) oluşturur. RTF (MS Word), PostScript, köprülenmiş PDF, sıkıştırılmış HTML, DocBook ve Unix el ile sayfalarda çıkış oluşturma desteği de vardır. Belgelenmemiş kaynak dosyalardan kod yapısını ayıklamak için Doxygen'i yapılandırabilirsiniz.

Uyarı

XML belgeleri açıklamaları meta veri değildir; derlenmiş derlemeye dahil değildir ve bu nedenle yansıma aracılığıyla erişilemezler.

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 dizesi işleçleri, parametreleri, dönüş değerlerini, genel tür parametrelerini, ref, inve out parametrelerini hesaba katmalıdır. 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şleyen 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 oluştururken aşağıdaki kuralları gözlemler:

  • Dizede boşluk yok.

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

    Karakter Üye türü Notes
    N isim alanı Bir ad alanına belge açıklamaları ekleyemezsiniz, ancak desteklendiği yerlerde bunlara başvuruda bulunabilirsiniz cref .
    T tür Tür bir sınıf, arabirim, yapı, numaralandırma veya temsilcidir.
    F field
    P mülk Dizin oluşturucuları veya diğer dizinlenmiş özellikleri içerir.
    M yöntem Oluşturucular ve işleçler gibi özel yöntemleri içerir.
    E etkinlik
    ! error string Dizenin geri kalanı hata hakkında bilgi sağlar. C# derleyicisi çözümlenemedi bağlantılar için hata bilgileri oluşturur.

  • Dizenin ikinci bölümü, ad alanının kökünden başlayarak öğenin tam adıdır. Öğenin adı, kapsayan türleri ve ad alanı noktalarla ayrılır. Öğenin adının dönemleri varsa, bunlar karma işareti ('#') ile değiştirilir. Dil bilgisi, hiçbir öğenin adında doğrudan bir karma işareti olmadığını varsayar. Örneğin, Dize oluşturucusunun tam adı "System.String.#ctor" şeklindedir.

  • Özellikler ve yöntemler için parantez içine alınmış parametre listesi aşağıdadır. Parametre yoksa, parantez yoktur. Parametreler virgülle ayrılır. Her parametrenin kodlaması doğrudan bir .NET imzasında nasıl kodlanmış olduğunu izler (Aşağıdaki listede yer alan tüm büyük harf öğ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 adı olarak temsil edilir.
    • İç türler (örneğin, ELEMENT_TYPE_I4, ELEMENT_TYPE_OBJECT, ELEMENT_TYPE_STRING, ELEMENT_TYPE_TYPEDBYREFve ELEMENT_TYPE_VOID) karşılık gelen tam türün tam adı olarak temsil edilir. Örneğin, System.Int32 veya System.TypedReference.
    • ELEMENT_TYPE_PTR , değiştirilen türden sonra '*' olarak temsil edilir.
    • ELEMENT_TYPE_BYREF , değiştirilen türden sonra '@' olarak temsil edilir.
    • ELEMENT_TYPE_CMOD_OPT , değiştirilen türün ardından bir '!' ve değiştirici sınıfının tam adı olarak temsil edilir.
    • ELEMENT_TYPE_SZARRAY , dizinin öğe türünden sonra "[]" olarak temsil edilir.
    • ELEMENT_TYPE_ARRAY [alt sınır:size,alt sınır:size] olarak gösterilir; burada virgül sayısı derece - 1 olur ve biliniyorsa her boyutun alt sınırları ve boyutu ondalık olarak gösterilir. Alt sınır ve boyut belirtilmezse atlanır. Belirli bir boyut için alt sınır ve boyut atlanırsa, ':' da atlanır. Örneğin, alt sınırlar ve belirtilmemiş boyutlar olarak 1 olan iki boyutlu bir dizi [1:,1:].

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

  • Genel türler için, türün adını arkasına bir arka uç ve sonra da genel tür parametrelerinin sayısını gösteren bir sayı eklenir. Örneğin: <member name="T:SampleClass`2"> olarak public class SampleClass<T, U>tanımlanan bir türün etiketidir. Genel türleri parametre olarak alan yöntemler için genel tür parametreleri, backticks ile önceden oluşturulmuş sayılar olarak belirtilir (örneğin, '0,'1). 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 '^' olarak temsil edilir. C# derleyicisi hiçbir zaman bu kodlamayı oluşturmaz.
    • ELEMENT_TYPE_CMOD_REQ , değiştirilen türe göre '|' ve değiştirici sınıfının tam adı olarak temsil edilir. C# derleyicisi hiçbir zaman bu kodlamayı oluşturmaz.
    • ELEMENT_TYPE_GENERICARRAY dizinin öğe türünden sonra "[?]" olarak temsil edilir. C# derleyicisi hiçbir zaman bu kodlamayı oluşturmaz.
    • ELEMENT_TYPE_FNPTR "=FUNC:type(signature)" olarak temsil edilir; burada type dönüş türüdür ve imza yöntemin bağımsız değişkenleridir. Bağımsız değişken yoksa parantezler atlanır. C# derleyicisi hiçbir zaman bu kodlamayı oluşturmaz.
    • Aşağıdaki imza bileşenleri, aşırı yüklenmiş yöntemleri ayırt etmek için kullanılmadığından temsil değildir:
      • calling convention
      • return type
      • 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() => 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 num, 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] => 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) => 1;
}

C# dil belirtimi

Daha fazla bilgi için belge açıklamalarında C# Dil Belirtimi ek bölümüne bakın.

  • Last updated on