C# belge açıklamaları için önerilen XML etiketleri

C# belge açıklamaları, çıktı belgelerinin yapısını tanımlamak için XML öğelerini kullanır. Bu özelliğin bir sonucu, belge açıklamalarınıza herhangi bir geçerli XML ekleyebilmenizdir. C# derleyicisi bu öğeleri çıkış XML dosyasına kopyalar. Açıklamalarınızda geçerli herhangi bir XML kullanabilirsiniz (geçerli html öğeleri dahil), birçok nedenden dolayı belge kodu önerilir.

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.

İpucu

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

C# kodunuzda XML belge etiketlerini kullanırken bilmeniz gereken bazı öneriler, genel kullanım örneği senaryoları ve bilmeniz gerekenler aşağıda belirtilmiştir. Belge açıklamalarınıza etiket koyabilirsiniz ancak bu makalede en yaygın dil yapıları için önerilen etiketler açıklanmaktadır. Şu önerilere uyun:

  • Tutarlılık açısından, genel olarak görünen tüm türleri ve bunların genel üyelerini belgele.
  • Özel üyeleri XML açıklamalarını kullanarak da belgeleyebilirsiniz. Ancak bu yaklaşım, kitaplığınızın iç (gizli olabilecek) çalışmalarını kullanıma sunar.
  • Türlerin ve üyelerinin en azından bir <summary> etiketi olmalıdır.
  • Tam duraklarla biten tümceleri kullanarak belge metni yazın.
  • Kısmi sınıflar tam olarak desteklenir ve belge bilgileri her tür için tek bir girişte birleştirilir. Kısmi üyenin her iki bildiriminin de belge açıklamaları varsa, uygulama bildirimindeki açıklamalar çıkış XML'sine yazılır.

XML belgeleri ile ///başlar. Yeni bir proje oluşturduğunuzda, şablonlar sizin için bazı başlangıç /// satırları ekler. Bu açıklamaların işlenmesinde bazı kısıtlamalar vardır:

  • Belgeler iyi biçimlendirilmiş XML olmalıdır. XML iyi biçimlendirilmemişse, derleyici bir uyarı oluşturur. Belge dosyası bir hatayla karşılaşıldığını belirten bir açıklama içerir.
  • Önerilen etiketlerden bazılarının özel anlamları vardır:
    • <param> etiketi parametreleri açıklar. Bu etiketi kullanırsanız, derleyici parametrenin mevcut olduğunu ve tüm parametrelerin belgelerde açıklandığını doğrular. Doğrulama başarısız olursa, derleyici bir uyarı görüntüler.
    • cref Bir kod öğesine başvurmak için özniteliğini herhangi bir etikete ekleyin. Derleyici bu kod öğesinin mevcut olduğunu doğrular. Doğrulama başarısız olursa, derleyici bir uyarı görüntüler. Derleyici, özniteliğinde açıklanan bir türü ararken tüm using yönergeleri dikkate alır cref .
    • Visual Studio içindeki IntelliSense, bir tür veya üye hakkında ek bilgi görüntülemek için <summary> etiketini kullanır.

      Not

      XML dosyası, tür ve üyeler hakkında tam bilgi sağlamaz (örneğin, herhangi bir tür bilgisi içermez). Bir tür veya üye hakkında tam bilgi almak için, belge dosyasını gerçek tür veya üye üzerindeki yansımayla birlikte kullanın.

  • Geliştiriciler kendi etiket kümelerini oluşturabilir. Derleyici bu etiketleri çıkış dosyasına kopyalar.

Önerilen etiketlerden bazıları herhangi bir dil öğesinde kullanılabilir. Diğerleri daha özel kullanımlara sahiptir. Son olarak, bazı etiketler belgelerinizdeki metni biçimlendirmek için kullanılır. Bu makalede, kullanımlarına göre düzenlenmiş önerilen etiketler açıklanmaktadır.

Derleyici, aşağıdaki listede öğelerin söz dizimini ve ardından tek bir * öğesini doğrular. Visual Studio, derleyici tarafından doğrulanan etiketler ve ardından aşağıdaki listede ** bulunan tüm etiketler için IntelliSense sağlar. Burada listelenen etiketlere ek olarak, derleyici ve Visual Studio <b>, <i>, <u>, <br/> ve <a> etiketlerini doğrular. Derleyici ayrıca, kullanım dışı HTML olan öğesini de doğrular <tt>.

Not

gibi <br/> HTML etiketleri, belge açıklamalarının içinde biçimlendirme için kullanışlıdır. Etiket <br/> satır sonları oluştururken, diğer HTML etiketleri metin biçimlendirmesi sağlar. Bu etiketler IntelliSense araç ipuçlarında ve oluşturulan belgelerde çalışır.

Not

Belge açıklamalarını ad alanına uygulayamazsınız.

Bir belge açıklamasının metninde açılı ayraçların görünmesini istiyorsanız, sırasıyla ve olan < ve >&lt; html kodlamasını &gt; kullanın. Aşağıdaki örnekte bu kodlama gösterilmektedir.

/// <summary>
/// This property always returns a value &lt; 1.
/// </summary>

Genel etiketler

<summary>

<summary>description</summary>

<summary> Bir türü veya tür üyesini açıklamak için etiketini kullanın. Tür açıklamasına ek bilgiler eklemek için kullanın <remarks> . Kod öğeleri için belge sayfalarına iç köprüler oluşturmak üzere DocFX ve Sandcastle gibi belge araçlarını etkinleştirmek için cref özniteliğini kullanın. Etiketin <summary> metni IntelliSense'te ve Nesne Tarayıcısı penceresinde görüntülenir.

<remarks>

<remarks>
description
</remarks>

etiketiyle <remarks> belirtilen bilgileri tamamlayarak bir tür veya tür üyesi hakkında bilgi eklemek için <summary>kullanın. Bu bilgiler Nesne Tarayıcısı penceresinde görüntülenir. Bu etiket daha uzun açıklamalar içerebilir. Markdown için bölümlerin kullanılmasının CDATA yazmayı daha kullanışlı hale getirebileceğini fark edebilirsiniz. Docfx gibi araçlar markdown metnini bölümler halinde CDATA işler.

Belge üyeleri

<returns>

<returns>description</returns>

<returns> Dönüş değerini açıklamak için yöntem bildirimi için açıklamadaki etiketini kullanın.

<param>

<param name="name">description</param>
  • name: Yöntem parametresinin adı. Adı tırnak işareti (") içine alın. Parametrelerin adları API imzası ile eşleşmelidir. Bir veya daha fazla parametre ele alınmazsa, derleyici bir uyarı görüntüler. Derleyici ayrıca değeri name yöntem bildirimindeki resmi bir parametreyle eşleşmiyorsa bir uyarı verir.

Yöntemin <param> parametrelerinden birini açıklamak için yöntem bildirimi için açıklamadaki etiketini kullanın. Birden çok parametreyi belgeleyemek için birden çok <param> etiket kullanın. Etiketin <param> metni IntelliSense, Nesne Tarayıcısı ve Kod Açıklaması Web Raporu'nda görünür.

<paramref>

<paramref name="name"/>
  • name: Başvurulacak parametrenin adı. Adı tırnak işareti (") içine alın.

<paramref> etiketi, kod açıklamalarındaki veya bloğu gibi <summary><remarks> bir sözcüğün parametreye başvurduğunu göstermek için bir yol sağlar. Xml dosyasını, bu sözcüğü kalın veya italik yazı tipi gibi farklı bir şekilde biçimlendirmek için işleyebilirsiniz.

<exception>

<exception cref="member">description</exception>
  • cref = "member": Geçerli derleme ortamından kullanılabilen bir özel duruma başvuru. Derleyici, verilen özel durumun mevcut olup olmadığını denetler ve çıkış XML'sindeki kurallı öğe adına çevrilir member . member tırnak işaretleri (") içinde görünmelidir.

<exception> etiketi, hangi özel durumların oluşturulabileceğini belirtmenize olanak tanır. Bu etiketi yöntemler, özellikler, olaylar ve dizin oluşturucuların tanımlarına uygulayın.

<value>

<value>property-description</value>

etiketi, <value> bir özelliğin temsil ettiği değeri açıklamanıza olanak tanır. Visual Studio .NET geliştirme ortamında kod sihirbazını kullanarak bir özellik eklediğinizde, yeni özellik için bir <summary> etiketi ekler. Özelliğin temsil ettiği değeri açıklamak için el ile bir <value> etiket eklersiniz.

Belge çıkışını biçimlendirme

<para>

<remarks>
    <para>
        This is an introductory paragraph.
    </para>
    <para>
        This paragraph contains more details.
    </para>
</remarks>

Metne <para> yapı eklemek için etiketin içinde , <summary>veya <remarks>gibi <returns>bir etiket kullanın. etiketi çift <para> aralıklı paragraf oluşturur. <br/> Tek bir aralıklı paragraf istiyorsanız etiketini kullanın.

İşte <para> ile <br/> arasındaki farkı gösteren bir örnek:

/// <summary>
/// Example using para tags:
/// <para>This is the first paragraph.</para>
/// <para>This is the second paragraph with double spacing.</para>
/// 
/// Example using br tags:
/// First line of text<br/>
/// Second line of text with single spacing<br/>
/// Third line of text
/// </summary>
public void FormattingExample()
{
    // This method demonstrates paragraph and line break formatting
}

<list>

<list type="bullet|number|table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>Assembly</term>
        <description>The library or executable built from a compilation.</description>
    </item>
    <item>
        <term>Namespace</term>
        <description>A logical grouping of related types such as classes and interfaces.</description>
    </item>
    <item>
        <term>Class</term>
        <description>A blueprint used to create objects, containing properties and methods.</description>
    </item>
</list>

<listheader> Bir tablonun veya tanım listesinin başlık satırını tanımlamak için bloğunu kullanın.

Tablo tanımlarken:

  • Başlığında için term bir giriş sağlayın.
  • Listedeki her öğeyi bir <item> blokla belirtin. Her itemiçin için bir giriş descriptionsağlayın.

Tanım listesi oluştururken:

  • Başlığında için term bir giriş sağlayın.
  • Listedeki her öğeyi bir <item> blokla belirtin. Her item birinin hem hem termde içermesi description gerekir.

Bir liste veya tablo gerektiği kadar çok <item> blok içerebilir.

<c>

<c>text</c>

Bir açıklama içindeki <c> metni kod olarak işaretlemek için etiketini kullanın. Birden çok satırı kod olarak belirtmek için kullanın <code> .

<code>

<code>
    var index = 5;
    index++;
</code>

<code> Birden çok kod satırı belirtmek için etiketini kullanın. Bir açıklama içindeki tek satırlı metni kod olarak işaretlemek için kullanın <c> .

<example>

<example>
This shows how to increment an integer.
<code>
    var index = 5;
    index++;
</code>
</example>

Bir yöntemin <example> veya başka bir kitaplık üyesinin nasıl kullanılacağına ilişkin bir örnek sağlamak için etiketini kullanın. Bir örnek genellikle etiketinin kullanılmasını <code> içerir.

<b>

<b>text</b>

Belge açıklamalarının <b> içinde metni kalın yapmak için etiketini kullanın. Derleyici ve Visual Studio bu HTML biçimlendirme etiketini doğrulayın. Biçimlendirilmiş metin IntelliSense ve oluşturulan belgelerde görünür.

<i>

<i>text</i>

Belge açıklamalarının <i> içinde metni italik yapmak için etiketini kullanın. Derleyici ve Visual Studio bu HTML biçimlendirme etiketini doğrulayın. Biçimlendirilmiş metin IntelliSense ve oluşturulan belgelerde görünür.

<u>

<u>text</u>

Belge açıklamalarının <u> içindeki metnin altını çizmek için etiketini kullanın. Derleyici ve Visual Studio bu HTML biçimlendirme etiketini doğrulayın. Biçimlendirilmiş metin IntelliSense ve oluşturulan belgelerde görünür.

<br/>

Line one<br/>Line two

Belge açıklamalarına <br/> satır sonu eklemek için etiketini kullanın. Çift aralıklı paragraf oluşturan etiketin <para> aksine, tek bir aralıklı paragraf istediğinizde bu etiketi kullanın.

<a>

<a href="https://example.com">Link text</a>

<a> Belge açıklamalarında köprü oluşturmak için etiketini kullanın. href özniteliği, bağlanılacak URL'yi belirtir. Derleyici ve Visual Studio bu HTML biçimlendirme etiketini doğrulayın.

Not

Derleyici ayrıca, kullanımdan kaldırılmış bir HTML etiketi olan <tt> etiketini de doğrular. Satır içi kod biçimlendirmesi için <c> etiketini kullanın.

Belge metnini yeniden kullanma

<inheritdoc>

<inheritdoc [cref=""] [path=""]/>

Xml açıklamalarını temel sınıflardan, arabirimlerden ve benzer yöntemlerden devralın. kullanarak inheritdoc, yinelenen XML açıklamalarının istenmeyen kopyalanmasını ve yapıştırılmasına engel olur ve XML açıklamalarını otomatik olarak eşitlenmiş olarak tutarsınız. Etiketi bir türe <inheritdoc> eklediğinizde, tüm üyeler açıklamaları da devralır.

  • cref: Belgeleri devralacak üyeyi belirtin. Devralınan etiketler geçerli üyede önceden tanımlanmış etiketleri geçersiz kılmaz.
  • path: Gösterilecek şekilde ayarlanmış bir düğüme neden olan XPath ifade sorgusu. Etiketleri devralınan belgelere dahil etmek veya dışlamak üzere filtrelemek için bu özniteliği kullanın.

Not

Visual Studio, belgelenmiş üyeleri geçersiz kılan veya uygulayan belgelenmemiş üyeler için XML belgelerini otomatik olarak devralır. Bu özellik, etikete gerek kalmadan IntelliSense ve Hızlı Bilgi'de devralınan <inheritdoc> belgeleri görüntüler. Ancak, bu otomatik devralma yalnızca Visual Studio IDE içinde geçerlidir ve derleyici tarafından oluşturulan XML belge dosyasını etkilemez.

Dağıttığınız kitaplıklardaki genel API'ler için etiketi açıkça kullanın <inheritdoc> veya oluşturulan XML belge dosyasının kitaplığınızın tüketicileri için gerekli tüm bilgileri içerdiğinden emin olmak için eksiksiz belgeler sağlayın.

Temel sınıflara veya arabirimlere XML açıklamalarınızı ekleyin ve inheritdoc'un açıklamaları sınıfları uygulamaya kopyalamasına izin verin. XML açıklamalarınızı zaman uyumlu yöntemlerinize ekleyin ve inheritdoc'un açıklamaları aynı yöntemlerin zaman uyumsuz sürümlerine kopyalamasına izin verin. Belirli bir üyenin açıklamalarını kopyalamak için özniteliğini cref kullanarak üyeyi belirtin.

<include>

<include file='filename' path='tagpath' />
<include file='filename' path='tagpath[@attribName]' />
<include file='filename' path='tagpath[@attribName="attribValue"]' />
<include file='filename' path='tagpath[@attribName1="attribValue1"][@attribName2="attribValue2"][@attribName3]' />

Öneri:

<include file='filename' path='tagpath[@name="id"]' />
  • filename: Belgeleri içeren XML dosyasının adı. Dosya adını kaynak kod dosyasına göre bir yolla niteleyebilirsiniz. Tek tırnak içine alın filename (' ').
  • path: içindeki etiketlerin filename yolu, kullanılacak XML açıklamasına yol açar. Yol, gibi namebir veya birden çok öznitelik içerebilir, ancak bunlar gerekli değildir. Özniteliklerin gibi iddeğerleri olabilir, ancak değerler de gerekli değildir. Olası öznitelikleri de içeren yolu tek tırnak içine alın (' ').
  • attribName, attribName1: İsteğe bağlı özniteliklerin adları.
  • attribValue, attribValue1: Özniteliklerin isteğe bağlı değerleri. Hiçbir değer belirtilmezse, içinde filenameaçıklama aranırken herhangi bir değer kabul edilir. Öznitelik değerini tırnak işareti (") içine alın.

etiketini kullanarak <include> , kaynak kodunuzdaki türleri ve üyeleri açıklayan başka bir dosyadaki açıklamalara başvurabilirsiniz. Dış dosya eklemek, belge açıklamalarını doğrudan kaynak kod dosyanıza yerleştirmenin bir alternatifidir. Belgeleri ayrı bir dosyaya yerleştirerek, belgelere kaynak kodundan ayrı olarak kaynak denetimi uygulayabilirsiniz. Bir kişi kaynak kod dosyasını kullanıma alabilir ve başka biri belge dosyasını kullanıma alabilir. <include> etiketi XML XPath söz dizimini kullanır. Kullanımınızı <include> özelleştirmenin yolları için XPath belgelerine bakın.

Örneğin, aşağıdaki kaynak kodu açıklamaları eklemek için etiketini kullanır <include> . Dosya yolu kaynağa göredir.

namespace MyNamespace;

public class MyType
{
    /// <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    /// <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    /// <include file="MyAssembly.xml" path="doc/members/member[@name='M:MyNamespace.MyType.MyMethod']/*" />
    public int MyMethod(int p) => p;
}

Ekleme dosyasının XML kaynağı aşağıdaki örnekte gösterilmiştir. C# derleyicisi tarafından oluşturulan XML dosyasıyla aynı şekilde yapılandırılmıştır. BIR XPath ifadesi bunları tanımlayabildiği sürece XML dosyası birden çok yöntem veya tür için metin içerebilir.

<?xml version="1.0"?>
<doc>
    <members>
        <member name="M:MyNamespace.MyType.MyMethod">
            <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
            <summary>This is the summary of MyMethod. It comes from the included file.</summary>
        </member>
    </members>
</doc>

Bu yöntemin XML çıkışı aşağıdaki örnekte gösterilmiştir:

<member name="M:MyNamespace.MyType.MyMethod(System.Int32)">
    <summary>This is the summary of MyMethod. It comes from the included file.</summary>
    <returns>This is the returns text of MyMethod. It comes from triple slash comments.</returns>
    <remarks>This is the remarks text of MyMethod. It comes from triple slash comments.</remarks>
    <param name="p">This is the description of the parameter p of MyMethod. It comes from the included file.</param>
</member>

İpucu

.NET Çalışma Zamanı ekibi, belgelerinde <include> etiketini kapsamlı bir şekilde kullanır. Depodadotnet/runtime birçok örnek görebilirsiniz.

<see>

<see cref="member"/>
<!-- or -->
<see cref="member">Link text</see>
<!-- or -->
<see href="link">Link Text</see>
<!-- or -->
<see langword="keyword"/>
  • cref="member": Geçerli derleme ortamından çağırabileceğiniz bir üyeye veya alana başvuru. Derleyici, verilen kod öğesinin mevcut olup olmadığını denetler ve çıkış XML'sindeki öğe adına geçirir member . Üyeyi tırnak işaretleri (") içine yerleştirin. Ayrı bir kapanış etiketi kullanarak için creffarklı bağlantı metni sağlayabilirsiniz.
  • href="link": Belirli bir URL'ye tıklanabilir bağlantı. Örneğin, <see href="https://github.com">GitHub</see>, https://github.com'e bağlanan GitHub metniyle tıklanabilir bir bağlantı oluşturur. Kod başvuruları için tasarlandığı ve dış URL'ler için tıklanabilir bağlantılar oluşturmadığı gibi href dış web sayfalarına bağlanırken yerine cref kullanıncref.
  • langword="keyword": Veya diğer geçerli anahtar sözcüklerden biri gibi true bir dil anahtar sözcüğü.

etiketi, <see> metnin içinden bir bağlantı belirtmenize olanak tanır. Metnin Ayrıca Bkz bölümüne yerleştirilmesi gerektiğini belirtmek için kullanın <seealso> . Kod öğelerinin belge sayfalarına iç köprüler oluşturmak için cref özniteliğini kullanın. Gibi cref="IDictionary{T, U}"genel bir türe veya yönteme başvuru belirtmek için tür parametrelerini ekleyin. Ayrıca, href köprü olarak işlev gösteren geçerli bir özniteliktir.

Dış URL'lere başvururken cref ve href arasındaki farkı gösteren bir örnek burada verilmiştir:

/// <summary>
/// This method demonstrates URL linking:
/// <see cref="https://learn.microsoft.com/dotnet/csharp"/> (won't create clickable link)
/// <see href="https://learn.microsoft.com/dotnet/csharp">C# documentation</see> (creates clickable link)
/// </summary>
public void UrlLinkingExample()
{
    // This method demonstrates the difference between cref and href for URLs
}

<seealso>

<seealso cref="member"/>
<!-- or -->
<seealso href="link">Link Text</seealso>
  • cref="member": Geçerli derleme ortamından çağırabileceğiniz bir üyeye veya alana başvuru. Derleyici, verilen kod öğesinin mevcut olup olmadığını denetler ve çıkış XML'sindeki öğe adına geçirir member . member tırnak işaretleri (") içinde görünmelidir.
  • href="link": Belirli bir URL'ye tıklanabilir bağlantı. Örneğin, <seealso href="https://github.com">GitHub</seealso>, https://github.com'e bağlanan GitHub metniyle tıklanabilir bir bağlantı oluşturur.

Etiketi, <seealso> Ayrıca Bkz bölümünde görünmesini isteyebileceğiniz metni belirtmenize olanak tanır. Metnin içinden bir bağlantı belirtmek için kullanın <see> . Etiketi etiketin seealso içine summary yerleştiremezsiniz.

cref özniteliği

cref XML belge etiketindeki öznitelik "kod başvurusu" anlamına gelir. Etiketin iç metninin tür, yöntem veya özellik gibi bir kod öğesi olduğunu belirtir. DocFX ve Sandcastle gibi belge araçları, türün cref veya üyenin belgelendiği sayfaya otomatik olarak köprü oluşturmak için öznitelikleri kullanır.

href özniteliği

href özniteliği, bir web sayfasına başvuru anlamına gelir. API'niz veya kitaplığınız hakkındaki çevrimiçi belgelere doğrudan başvurmak için bunu kullanabilirsiniz. Dış URL'lere belge açıklamalarınızda bağlanmanız gerektiğinde, bağlantıların IntelliSense araç ipuçlarında ve oluşturulan belgelerde tıklanabilir olmasını sağlamak için href yerine cref kullanın.

Genel türler ve yöntemler

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: tür parametresinin adı. Adı tırnak işareti (") içine alın.

Etiket, <typeparam> tür parametresini açıklamak üzere genel bir tür veya yöntem bildirimi için açıklama içinde kullanılmalıdır. Genel türün veya yöntemin her tür parametresi için bir etiket ekleyin. Etiketin <typeparam> metni IntelliSense'te görüntülenir.

<typeparamref>

<typeparamref name="TKey"/>
  • TKey: tür parametresinin adı. Adı tırnak işareti (") içine alın.

Belge dosyasının tüketicilerinin sözcüğü italik gibi farklı bir şekilde biçimlendirmesini sağlamak için bu etiketi kullanın.

Kullanıcı tanımlı etiketler

Bu makalede özetlenen tüm etiketler, C# derleyicisi tarafından tanınan etiketleri temsil edilir. Ancak, bir kullanıcı kendi etiketlerini tanımlamakta serbesttir. Sandcastle gibi araçlar ve <event>gibi <note> ek etiketler için destek getirir ve hatta ad alanlarını belgeleme desteği sağlar. Özel veya şirket içi belge oluşturma araçları standart etiketlerle de kullanılabilir ve HTML'den PDF'ye birden çok çıkış biçimi desteklenebilir.

  • Last updated on