Aracılığıyla paylaş

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# 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. Her durumda şu önerilere uymalısınız:

  • Tutarlılık açısından, herkese açık tüm türler ve bunların genel üyeleri belgelenmelidir.
  • Özel üyeler XML açıklamaları kullanılarak da belgelenebilir. Ancak, 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.
  • Belge metni, tam duraklarla biten tümceler kullanılarak yazılmalıdır.
  • 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çıklamak için kullanılır. Kullanılırsa, 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.
    • Özniteliği, cref bir kod öğesine başvurmak için herhangi bir etikete eklenebilir. 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 .
    • Etiketi <summary> , Visual Studio içindeki IntelliSense tarafından bir tür veya üye hakkında ek bilgi görüntülemek için kullanılı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>ve <br/> etiketlerini de doğrular<a>. 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ı ad alanına uygulanamaz.

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. Bu kodlama aşağıdaki örnekte gösterilmiştir.

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

Genel etiketler

<summary>

<summary>description</summary>

Etiketin <summary> bir türü veya tür üyesini tanımlamak için kullanılması gerekir. 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>

<remarks> etiketi, ile <summary>belirtilen bilgilere ek olarak bir tür veya tür üyesi hakkında bilgi eklemek için kullanılır. 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>

Etiket <returns> , dönüş değerini açıklamak üzere bir yöntem bildirimi için açıklama içinde kullanılmalıdır.

<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.

etiketi, <param> yöntemin parametrelerinden birini açıklamak üzere bir yöntem bildiriminin açıklamasında kullanılmalıdır. 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üntülenir.

<paramref>

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

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

<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 etiket yöntemler, özellikler, olaylar ve dizin oluşturucuların tanımlarına uygulanabilir.

<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ı aracılığıyla bir özellik eklediğinizde, yeni özellik için bir <summary> etiket 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>

<para> Etiket, , <remarks>veya <returns>gibi <summary>bir etiketin içinde kullanım içindir ve metne yapı eklemenize olanak tanır. 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>
</list>

Blok <listheader> , bir tablonun veya tanım listesinin başlık satırını tanımlamak için kullanılır.

Tablo tanımlarken:

  • Yalnızca başlığında için term bir girdi sağlamanız gerekir.
  • Listedeki her öğe bir <item> blokla belirtilir. Her itemiçin yalnızca için descriptionbir giriş sağlamanız gerekir.

Tanım listesi oluştururken:

  • Başlığında için term bir giriş sağlamanız gerekir.
  • Listedeki her öğe bir <item> blokla belirtilir. 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>

etiketi, <c> bir açıklama içindeki metnin kod olarak işaretlenmesi gerektiğini belirtmek için size bir yol sağlar. Birden çok satırı kod olarak belirtmek için kullanın <code> .

<code>

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

Etiketi <code> , birden çok kod satırı belirtmek için kullanılır. Bir açıklama içindeki tek satırlı metnin kod olarak işaretlenmesi gerektiğini belirtmek için kullanın <c> .

<example>

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

etiketi, <example> bir yöntemin veya başka bir kitaplık üyesinin nasıl kullanılacağını gösteren bir örnek belirtmenize olanak tanır. Bir örnek genellikle etiketinin kullanılmasını <code> içerir.

<b>

<b>text</b>

<b> Etiket, belge açıklamalarında metni kalın yapmak için kullanılır. Bu HTML biçimlendirme etiketi derleyici ve Visual Studio tarafından doğrulanır ve biçimlendirilmiş metin IntelliSense ve oluşturulan belgelerde görünür.

<i>

<i>text</i>

<i> Etiket, belge açıklamalarında metin italik yapmak için kullanılır. Bu HTML biçimlendirme etiketi derleyici ve Visual Studio tarafından doğrulanır ve biçimlendirilmiş metin IntelliSense ve oluşturulan belgelerde görünür.

<u>

<u>text</u>

<u> Etiket, belge açıklamalarının içindeki metnin altını çizmek için kullanılır. Bu HTML biçimlendirme etiketi derleyici ve Visual Studio tarafından doğrulanır ve biçimlendirilmiş metin IntelliSense ve oluşturulan belgelerde görünür.

<br/>

Line one<br/>Line two

<br/> Etiket, belge açıklamalarına satır sonu eklemek için kullanılır. Ç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> Etiket, belge açıklamalarında köprü oluşturmak için kullanılır. href özniteliği, bağlanılacak URL'yi belirtir. Bu HTML biçimlendirme etiketi derleyici ve Visual Studio tarafından doğrulanır.

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. kullanmak inheritdoc , yinelenen XML açıklamalarının istenmeyen kopyalanmasını ve yapıştırılması ortadan kaldırır ve XML açıklamalarının otomatik olarak eşitlenmesini sağlar. Etiketi bir türe <inheritdoc> eklediğinizde, tüm üyeler açıklamaları da devralır.

  • cref: Belgeleri devralacak üyeyi belirtin. Geçerli üyede zaten tanımlanmış etiketler devralınanlar tarafından geçersiz kılınmıyor.
  • path: Gösterilecek şekilde ayarlanmış bir düğüme neden olan XPath ifade sorgusu. Bu özniteliği, etiketleri devralınan belgeleri içerecek veya dışlamak üzere filtrelemek için kullanabilirsiniz.

Not

Visual Studio, belgelenmiş üyeleri geçersiz kılan veya uygulayan belgelenmemiş üyeler için XML belgelerinin otomatik devralmasını sağlar. 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, oluşturulan XML belge dosyasının <inheritdoc> kitaplığınızın tüketicileri için gerekli tüm bilgileri içerdiğinden emin olmak için etiketi açıkça kullanmanız veya eksiksiz belgeler sağlamanız gerekir.

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 istiyorsanız, üyeyi cref belirtmek için özniteliğini kullanırsınız.

<include>

<include file='filename' path='tagpath[@name="id"]' />
  • filename: Belgeleri içeren XML dosyasının adı. Dosya adı, kaynak kod dosyasına göre bir yol ile nitelenebilir. Tek tırnak içine alın filename (' ').
  • tagpath: içindeki filename etiketlerin yolu etiketine nameyol açar. Yolu tek tırnak içine alın (' ').
  • name: Açıklamaların önündeki etiketteki ad tanımlayıcısı; name bir idöğesine sahiptir.
  • id: Açıklamaların önündeki etiketin kimliği. Kimliği tırnak işareti (") içine alın.

etiketi, <include> kaynak kodunuzdaki türleri ve üyeleri açıklayan başka bir dosyadaki açıklamalara başvurmanızı sağlar. 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, etiketi belgelerinde kapsamlı bir şekilde kullanır <include> . 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ğrılabilecek 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 "cref" için farklı bağlantı metni sağlayabilirsiniz.
  • href="link": Belirli bir URL'ye tıklanabilir bağlantı. Örneğin, <see href="https://github.com">GitHub</see> bağlantısı olan GitHubmetinle https://github.com tıklanabilir bir bağlantı oluşturur. Başka web sayfalarına bağlantı verirken href yerine cref kullanın, çünkü cref kod başvuruları için tasarlanmıştır ve dış URL'ler için tıklanabilir bağlantılar oluşturmaz.
  • 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 eklersiniz. 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ğrılabilecek 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> bağlantısı olan GitHubmetinle https://github.com 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 <note>gibi <event> 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