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

  • Makale

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.

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ında hatayla karşılaşıldığını belirten bir açıklama bulunur.
  • Ö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 deyimleri 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 bunları çı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 , , <i><u>, <br/>ve <a> etiketlerini de doğrular<b>. Derleyici ayrıca, kullanım dışı HTML olan öğesini de doğrular <tt>.

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 &lt; ve >&gt; html kodlamasını < kullanın. Bu kodlama aşağıdaki örnekte gösterilmiştir.

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

Genel etiketler

<Özet>

<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 açıklamaları> kullanın<. 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.

<Açıklamalar>

<remarks>
description
</remarks>

<remarks> Etiket, bir tür veya tür üyesi hakkında bilgi eklemek için kullanılır ve özetle>< belirtilen bilgileri tamamlar. 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 getirdiğini fark edebilirsiniz. Docfx gibi araçlar markdown metnini bölümler halinde CDATA işler.

Belge üyeleri

<Döndürür>

<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ı çift 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ı çift tırnak işareti (" ") içine alın.

<paramref> etiketi, kod açıklamalarındaki bir sözcüğün (örneğin, veya <remarks> bloğundaki) <summary> 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.

<Özel durum>

<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 çift tırnak işareti (" ") 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 <özet> 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>

Etiket<para>, özet>,< açıklamalar veya <dönüşler>> gibi <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.

<listele>

<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 giriş sağlamanız gerekir. Listedeki her öğe bir <item> blokla belirtilir. Tanım listesi oluştururken hem hem descriptionde term belirtmeniz gerekir. Ancak tablo, madde işaretli liste veya numaralandırılmış liste için yalnızca için descriptionbir giriş sağlamanız 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 kodu kullanın<.

<kod>

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

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

<Örnek>

<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 kod> etiketinin kullanılmasını <içerir.

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 eklediğinizde, tüm üyelerin <inheritdoc> açıklamaları da devralacağını unutmayın.

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

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 idolacaktır.
  • id: Açıklamaların önündeki etiketin kimliği. Kimliği çift 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> . Depoda arama yaparak dotnet/runtime birçok örnek görebilirsiniz.

<bkz.>

<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 çift tırnak işareti (" ") 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 https://github.commetinle GitHub tıklanabilir bir bağlantı oluşturur.
  • 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 seealso> kullanın<. 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ü işlevi görecek geçerli bir özniteliktir.

<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 çift tırnak işareti (" ") 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 https://github.commetinle GitHub 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 bkz. seçeneğini kullanın<.> Etiketi etiketin seealso içinde iç içe yerleştiremezsiniz summary .

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.

Genel türler ve yöntemler

<typeparam>

<typeparam name="TResult">The type returned from this method</typeparam>
  • TResult: tür parametresinin adı. Adı çift 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ı çift 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

Yukarıda özetlenen tüm etiketler, C# derleyicisi tarafından tanınan etiketleri gösterir. Ancak, bir kullanıcı kendi etiketlerini tanımlamakta serbesttir. Sandcastle gibi araçlar olay> ve <not> gibi< ek etiketler için destek getirir ve hatta ad alanlarını belgeleme desteği sunar. Ö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.