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.

C# dili başvuru belgesi, C# dilinin en son yayımlanan sürümünü gösterir. Ayrıca, yaklaşan dil sürümü için genel önizlemelerdeki özelliklere yönelik ilk belgeleri içerir.

Belgelerde ilk olarak dilin son üç sürümünde veya geçerli genel önizlemelerde sunulan tüm özellikler tanımlanır.

Tavsiye

Bir özelliğin C# dilinde ilk tanıtıldığı zamanları bulmak için C# dil sürümü geçmişi makalesine bakın.

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. 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çeneği etkinleştirdiğinizde, derleyici xml belge açıklamaları olmadan projenizde 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ın:

  • /// 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;) kullanın. 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}") kullanın. Ö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 eklemezseniz, 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. Derleyici bunları derlenmiş derlemeye dahil etmediğinden yansıma aracılığıyla erişilemez.

Kimlik dizeleri

Derleyici, her türü veya üyeyi çıkış XML dosyasındaki bir öğeye yazar. Her öğenin türü veya üyeyi tanımlayan benzersiz bir kimlik dizesi vardır. Kimlik dizesi işleçler, parametreler, dönüş değerleri, genel tür parametreleri, ref, inve out parametreleri hakkında bilgi içerir. 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 şu kuralları izler:

  • Dize boşluk içermiyor.

  • Dize tek bir karakter ve üye türünü tanımlayan iki nokta üst üste ile başlar. Aşağıdaki üye türlerini kullanın:

    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, derleyici bunları karma işareti ('#') ile değiştirir. 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.
    • , ELEMENT_TYPE_OBJECT, , ELEMENT_TYPE_STRINGELEMENT_TYPE_TYPEDBYREFve ELEMENT_TYPE_VOIDgibi ELEMENT_TYPE_I4iç türler, ilgili 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 (op_Implicit ve op_Explicit) için yöntem 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 derleyicinin bir sınıf ve üyeleri için kimlik dizelerini nasıl oluşturduğ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