Ek D Dokümantasyon açıklamaları

Bu ek bilgilendirme amaçlıdır.

D.1 Genel

C#, programcıların XML metni içeren bir açıklama sözdizimi kullanarak kodlarını belgelemeleri için bir mekanizma sağlar. Kaynak kod dosyalarında, belirli bir forma sahip yorumlar, bu yorumlardan ve onlardan önce gelen kaynak kod öğelerinden XML üretmek için bir aracı yönlendirmek için kullanılabilir. Bu tür bir sözdizimini kullanan yorumlara belge yorumları denir. Kullanıcı tanımlı bir türden (sınıf, temsilci veya arabirim gibi) veya bir üyeden (alan, olay, özellik veya yöntem gibi) hemen önce gelmelidirler. XML oluşturma aracı, belge oluşturucu olarak adlandırılır. (Bu oluşturucu C# derleyicisinin kendisi olabilir, ancak olması gerekmez.) Dokümantasyon oluşturucu tarafından üretilen çıktıya dokümantasyon dosyası denir. Bir belge dosyası, bir belge görüntüleyicisine giriş olarak kullanılır; Tür bilgilerinin ve ilgili belgelerinin bir tür görsel görüntüsünü üretmeyi amaçlayan bir araç.

Belge açıklamalarının sözdizimini kontrol etmek için uyumlu bir C# derleyicisi gerekli değildir; Bu tür yorumlar sadece sıradan yorumlardır. Bununla birlikte, uyumlu bir derleyicinin bu tür bir kontrol yapmasına izin verilir.

Bu belirtim, belge açıklamalarında kullanılacak bir dizi standart etiket önerir, ancak bu etiketlerin kullanılması gerekli değildir ve iyi biçimlendirilmiş XML kurallarına uyulduğu sürece istenirse başka etiketler de kullanılabilir. CLI'yi hedefleyen C# uygulamaları için, belge oluşturucu ve belge dosyasının biçimi hakkında da bilgi sağlar. Belge görüntüleyici hakkında hiçbir bilgi sağlanmadı.

D.2 Giriş

Belirli bir forma sahip yorumlar, bu yorumlardan ve öncesinde gelen kaynak kodu öğelerinden XML üretmek için bir aracı yönlendirmek için kullanılabilir. Bu tür yorumlar,üç eğik çizgi () ile başlayan Single_Line_Comment s ( ) veya bir eğik çizgi ve iki yıldız (///) ile başlayan Delimited_Comments (/**) 'dir. Bunlar, kullanıcı tanımlı bir türden veya açıklama ekledikleri bir üyeden hemen önce gelmelidir. Öznitelik bölümleri (§23.3) bildirimlerin bir parçası olarak kabul edilir, bu nedenle belge açıklamaları bir türe veya üyeye uygulanan özniteliklerden önce olmalıdır.

Açıklama amacıyla, belge yorumlarının biçimi aşağıda iki dilbilgisi kuralı olarak gösterilmiştir: Single_Line_Doc_Comment ve Delimited_Doc_Comment. Ancak, bu kurallar C# dilbilgisinin bir parçası değildir , bunun yerine sırasıyla belirli Single_Line_Comment biçimlerini ve Delimited_Comment lexer kurallarını temsil eder.

Sözdizimi:

Single_Line_Doc_Comment
    : '///' Input_Character*
    ;
   
Delimited_Doc_Comment
    : '/**' Delimited_Comment_Section* ASTERISK+ '/'
    ;

Bir Single_Line_Doc_Comment, geçerli Single_Line_Doc_Comment bitişik /// her birinde karakterleri takip eden bir Boşluk karakteri varsa, bu Boşluk karakteri XML çıktısına dahil edilmez.

Bir Delimited_Doc_Comment, ikinci satırdaki boşluk olmayan ilk karakter birASTERISK ise ve isteğe bağlı Boşluk karakterlerinin aynı deseni ve Delimited_Doc_Comment içindeki satırların her birinin başında bir ASTERISK karakteri tekrarlanıyorsa, tekrarlanan desenin karakterleri XML çıktısına dahil edilmez. Desen, ASTERISK karakterinden önce olduğu kadar sonra da Boşluk karakterlerini içerebilir.

Örnek:

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
public class Point
{
    /// <summary>
    /// Method <c>Draw</c> renders the point.
    /// </summary>
    void Draw() {...}
}

Dokümantasyon açıklamaları içindeki metin, XML (http://www.w3.org/TR/REC-xml) kurallarına göre iyi bir şekilde biçimlendirilmelidir. XML yanlış biçimlendirilmişse, bir uyarı oluşturulur ve belge dosyası bir hatayla karşılaşıldığını belirten bir açıklama içerir.

Geliştiriciler kendi etiket kümelerini oluşturmakta özgür olsalar da, önerilen bir küme §D.3'te tanımlanmıştır. Önerilen etiketlerden bazılarının özel anlamları vardır:

• Etiket <param> , parametreleri tanımlamak için kullanılır. Böyle bir etiket kullanılırsa, dokümantasyon oluşturucunun belirtilen parametrenin var olduğunu ve tüm parametrelerin dokümantasyon açıklamalarında açıklandığını doğrulaması gerekir. Bu tür bir doğrulama başarısız olursa, belge oluşturucu bir uyarı verir.

• Özniteliği cref , bir kod öğesine başvuru sağlamak için herhangi bir etikete eklenebilir. Belge oluşturucunun bu kod öğesinin var olduğunu doğrulaması gerekir. Doğrulama başarısız olursa, belge oluşturucu bir uyarı verir. Bir cref öznitelik içinde açıklanan bir adı ararken, belge oluşturucu, kaynak kodunda görünen using deyimlerine göre ad alanı görünürlüğüne saygı göstermelidir. Genel olan kod öğeleri için, normal genel sözdizimi (örneğin, "List<T>") kullanılamaz çünkü geçersiz XML üretir. Braket yerine diş teli kullanılabilir (örn; "List{T}") veya XML kaçış sözdizimi kullanılabilir (örneğin, "List<T>").

• Etiket <summary> , bir tür veya üye hakkında ek bilgiler görüntülemek için bir belge görüntüleyicisi tarafından kullanılmak üzere tasarlanmıştır.

• Etiket <include> , harici bir XML dosyasından bilgi içerir.

Belge dosyasının tür ve üyeler hakkında tam bilgi sağlamadığını dikkatlice unutmayın (örneğin, herhangi bir tür bilgisi içermez). Bir tür veya üye hakkında bu tür bilgileri almak için, dokümantasyon dosyası, tür veya üye üzerindeki yansıma ile birlikte kullanılmalıdır.

Kısmi bir tür veya kısmi bir yöntem, her biri bir veya daha fazla derleme biriminde olabilen ve her biri bir veya daha fazla belge açıklamasına sahip olabilen birden çok parça halinde bildirilebilir. Kısmi bir yöntem tipik olarak bir "kısmi beyanı tanımlama" ve bir "kısmi uygulama beyanı" içerir.

Kısmi bir tür için, bu türe (varsa, her bir parçasından) doğrudan uygulanan belge açıklamalarının tümü, belge dosyasına belirtilmemiş bir sırayla yazılır.

Kısmi bir yöntem için:

• Tanımlayıcı bir kısmi beyannameye karşılık gelen bir uygulama kısmi beyanı yoksa, bu tanımlayıcı kısmi beyannamedeki tüm belge açıklamaları yok sayılır (çünkü bu beyan kaldırılacaktır).
• Aksi takdirde, uygulayıcı kısmi beyanın herhangi bir dokümantasyon açıklaması varsa, bunlar dokümantasyon dosyasına yazılır ve tanımlayıcı kısmi beyandaki tüm dokümantasyon yorumları göz ardı edilir.
• Aksi takdirde, tanımlayıcı kısmi bildirimdeki tüm dokümantasyon açıklamaları dokümantasyon dosyasına yazılır.

D.3 Önerilen etiketler

D.3.1 Genel

Dokümantasyon oluşturucu, XML kurallarına göre geçerli olan herhangi bir etiketi kabul etmeli ve işlemelidir. Aşağıdaki etiketler, kullanıcı belgelerinde yaygın olarak kullanılan işlevselliği sağlar. (Tabii ki, başka etiketler de mümkündür.)

Etiket	Referans	Amaç
<c>	§D.3.2	Metni kod benzeri bir yazı tipinde ayarlayın
<code>	§D.3.3	Bir veya daha fazla kaynak kodu veya program çıktısı satırı ayarlayın
<example>	§D.3.4	Bir örnek belirtin
<exception>	§D.3.5	Bir yöntemin oluşturabileceği özel durumları tanımlar
<include>	§D.3.6	Harici bir dosyadan XML içerir
<list>	§D.3.7	Liste veya tablo oluşturma
<para>	§D.3.8	Metne yapı eklenmesine izin ver
<param>	§D.3.9	Bir yöntem veya yapıcı için bir parametre açıklama
<paramref>	§D.3.10	Bir sözcüğün parametre adı olduğunu belirleme
<permission>	§D.3.11	Bir üyenin güvenlik erişilebilirliğini belgeleyin
<remarks>	§D.3.12	Bir tür hakkında ek bilgileri açıklama
<returns>	§D.3.13	Bir yöntemin dönüş değerini açıklama
<see>	§D.3.14	Bir bağlantı belirtin
<seealso>	§D.3.15	Ayrıca Bkz. girdisi oluşturma
<summary>	§D.3.16	Bir türü veya türün bir üyesini açıklama
<typeparam>	§D.3.17	Genel bir tür veya yöntem için bir tür parametresi açıklama
<typeparamref>	§D.3.18	Bir sözcüğün bir tür parametresi adı olduğunu belirleme
<value>	§D.3.19	Bir mülkü tanımlayın

D.3.2 <c>

Bu etiket, bir açıklama içindeki bir metin parçasının, bir kod bloğu için kullanılana benzer özel bir yazı tipinde ayarlanması gerektiğini belirten bir mekanizma sağlar. Gerçek kod satırları için (<code> kullanın .

Sözdizimi:

<c> Metin</c>

Örnek:

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
public class Point
{
}

D.3.3 <kodu>

Bu etiket, bazı özel yazı tiplerinde bir veya daha fazla kaynak kodu veya program çıktısı satırı ayarlamak için kullanılır. Anlatımdaki küçük kod parçaları için (<c>) kullanın .

Sözdizimi:

<code> Kaynak kodu veya program çıktısı</code>

Örnek:

public class Point
{
    /// <summary>
    /// This method changes the point's location by the given x- and y-offsets.
    /// <example>
    /// For example:
    /// <code>
    /// Point p = new Point(3,5);
    /// p.Translate(-1,3);
    /// </code>
    /// results in <c>p</c>'s having the value (2,8).
    /// </example>
    /// </summary>
    public void Translate(int dx, int dy)
    {
        ...
    }
}

D.3.4 <örneği>

Bu etiket, bir yöntemin veya başka bir kitaplık üyesinin nasıl kullanılabileceğini belirtmek için bir açıklama içindeki örnek koda izin verir. Normalde, bu aynı zamanda etiketin <code> (§D.3.3) kullanımını da içerir.

Sözdizimi:

<example> Açıklama</example>

Örnek:

Bir örnek için (<code>) bakınız .

D.3.5 <istisnası>

Bu etiket, bir yöntemin oluşturabileceği özel durumları belgelemek için bir yol sağlar.

Sözdizimi:

<exception cref=" üye">Açıklama</exception>

nerede

• cref=" üye" bir üyenin adıdır. Belge oluşturucu, verilen üyenin var olup olmadığını kontrol eder ve üyeyi belge dosyasındaki kurallı öğe adına çevirir.
• Açıklama , özel durumun oluşturulduğu durumların bir açıklamasıdır.

Örnek:

class PrimaryFileFormatCorruptException : System.Exception { ... }
class PrimaryFileLockedOpenException : System.Exception { ... }

public class DataBaseOperations
{
    /// <exception cref="PrimaryFileFormatCorruptException">
    /// Thrown when the primary file is corrupted.
    /// </exception>
    /// <exception cref="PrimaryFileLockedOpenException">
    /// Thrown when the primary file is already open.
    /// </exception>
    public static void ReadRecord(int flag)
    {
        if (flag == 1)
        {
            throw new PrimaryFileFormatCorruptException();
        }
        else if (flag == 2)
        {
            throw new PrimaryFileLockedOpenException();
        }
        ...
    }
}

D.3.6 <şunları içerir:>

Bu etiket, kaynak kod dosyasının dışında olan bir XML belgesinden bilgi eklemeye izin verir. Harici dosyanın iyi biçimlendirilmiş bir XML belgesi olması gerekir ve bu belgeden hangi XML'in dahil edileceğini belirtmek için bu belgeye bir XPath ifadesi uygulanır. Etiket <include> daha sonra harici belgeden seçilen XML ile değiştirilir.

Söz dizimi:

<include file=" Dosyaadı" path="xpath yolu" />

nerede

• file=" Dosyaadı" , harici bir XML dosyasının dosya adıdır. Dosya adı, include etiketini içeren dosyaya göre yorumlanır.
• path=" xpath" yolu , harici XML dosyasındaki XML'in bir kısmını seçen bir XPath ifadesidir.

Örnek:

Kaynak kodu şöyle bir bildirim içeriyorsa:

/// <include file="docs.xml" path='extradoc/class[@name="IntList"]/*' />
public class IntList { ... }

Ve harici dosya "docs.xml" aşağıdaki içeriğe sahipti:

<?xml version="1.0"?>
<extradoc>
    <class name="IntList">
        <summary>
            Contains a list of integers.
        </summary>
    </class>
    <class name="StringList">
        <summary>
            Contains a list of strings.
        </summary>
    </class>
</extradoc>

Ardından, kaynak kodu içeriyormuş gibi aynı belgelerin çıktısı alınır:

/// <summary>
/// Contains a list of integers.
/// </summary>
public class IntList { ... }

D.3.7 <listesi>

Bu etiket, bir öğe listesi veya tablosu oluşturmak için kullanılır. Bir tablonun veya tanım listesinin başlık satırını tanımlamak için bir <listheader> blok içerebilir. (Bir tablo tanımlanırken, başlıkta yalnızca terim için bir giriş yapılması gerekir.)

Listedeki her öğe bir <item> blokla belirtilir. Bir tanım listesi oluştururken, hem terim hem de açıklama belirtilmelidir. Ancak, tablo, madde işaretli liste veya numaralandırılmış liste için yalnızca açıklamanın belirtilmesi gerekir.

Sözdizimi:

<list type="bullet" | "number" | "table">
    <listheader>
        <term>term</term>
        <description>description</description>
    </listheader>
    <item>
        <term>term</term>
        <description>description</description>
    </item>
    ...
    <item>
        <term>term</term>
        <description>description</description>
    </item>
</list>

nerede

• terim , tanımı açıklamada olan, tanımlanacak terimdir.
• Açıklama , madde işaretli veya numaralandırılmış listedeki bir öğe ya da bir terimin tanımıdır.

Örnek:

public class MyClass
{
    /// <summary>Here is an example of a bulleted list:
    /// <list type="bullet">
    /// <item>
    /// <description>Item 1.</description>
    /// </item>
    /// <item>
    /// <description>Item 2.</description>
    /// </item>
    /// </list>
    /// </summary>
    public static void Main()
    {
        ...
    }
}

D.3.8 <para>

Bu etiket, (<summary>) veya (<returns>) gibi diğer etiketlerin içinde kullanım içindir ve metne yapı eklenmesine izin verir.

Sözdizimi:

<para> içerik</para>

nerede

• İçerik , paragrafın metnidir.

Örnek:

public class Point
{
    /// <summary>This is the entry point of the Point class testing program.
    /// <para>
    /// This program tests each method and operator, and
    /// is intended to be run after any non-trivial maintenance has
    /// been performed on the Point class.
    /// </para>
    /// </summary>
    public static void Main() 
    {
        ...
    }
}

D.3.9 <paragrafı>

Bu etiket, bir yöntem, oluşturucu veya dizin oluşturucu için bir parametreyi açıklamak için kullanılır.

Sözdizimi:

<param name=" ad">Açıklama</param>

nerede

• name , parametrenin adıdır.
• description , parametrenin bir açıklamasıdır.

Örnek:

public class Point
{
    /// <summary>
    /// This method changes the point's location to
    /// the given coordinates.
    /// </summary>
    /// <param name="xPosition">the new x-coordinate.</param>
    /// <param name="yPosition">the new y-coordinate.</param>
    public void Move(int xPosition, int yPosition)
    {
        ...
    }
}

D.3.10 <paramref>

Bu etiket, bir kelimenin bir parametre olduğunu belirtmek için kullanılır. Dokümantasyon dosyası, bu parametreyi farklı bir şekilde biçimlendirmek için işlenebilir.

Sözdizimi:

<paramref name=" ad"/>

nerede

• name , parametrenin adıdır.

Örnek:

public class Point
{
    /// <summary>This constructor initializes the new Point to
    /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
    /// </summary>
    /// <param name="xPosition">the new Point's x-coordinate.</param>
    /// <param name="yPosition">the new Point's y-coordinate.</param>
    public Point(int xPosition, int yPosition)
    {
        ...
    }
}

D.3.11 <izin>

Bu etiket, bir üyenin güvenlik erişilebilirliğinin belgelenmesini sağlar.

Sözdizimi:

<permission cref=" üye">Açıklama</permission>

nerede

• Üye , bir üyenin adıdır. Belge oluşturucu, verilen kod öğesinin var olup olmadığını kontrol eder ve üyeyi belge dosyasındaki kurallı öğe adına çevirir.
• Açıklama , üyeye erişimin bir açıklamasıdır.

Örnek:

public class MyClass
{
    /// <permission cref="System.Security.PermissionSet">
    /// Everyone can access this method.
    /// </permission>
    public static void Test()
    {
        ...
    }
}

D.3.12 <açıklamalar>

Bu etiket, bir tür hakkında ek bilgi belirtmek için kullanılır. Türün kendisini ve bir türün üyelerini tanımlamak için (<summary>) ifadesini kullanın .

Sözdizimi:

<remarks> Açıklama</remarks>

nerede

• Açıklama , açıklamanın metnidir.

Örnek:

/// <summary>
/// Class <c>Point</c> models a point in a two-dimensional plane.
/// </summary>
/// <remarks>
/// Uses polar coordinates
/// </remarks>
public class Point
{
    ...
}

D.3.13 <iadeleri>

Bu etiket, bir yöntemin dönüş değerini açıklamak için kullanılır.

Sözdizimi:

<returns> Açıklama</returns>

nerede

• Açıklama , döndürülen değerin bir açıklamasıdır.

Örnek:

public class Point
{
    /// <summary>
    /// Report a point's location as a string.
    /// </summary>
    /// <returns>
    /// A string representing a point's location, in the form (x,y),
    /// without any leading, trailing, or embedded whitespace.
    /// </returns>
    public override string ToString() => $"({X},{Y})";
    public int X { get; set; }
    public int Y { get; set; }
}

Bkz. D.3.14 <>

Bu etiket, metin içinde bir bağlantının belirtilmesini sağlar. <seealso> alt maddesinde görünecek metni belirtmek için (§D.3.15) kullanın .

Sözdizimi:

<see cref=" üye" href="URL" langword="anahtar sözcük" />

nerede

• Üye , bir üyenin adıdır. Belge oluşturucu, verilen kod öğesinin var olup olmadığını kontrol eder ve oluşturulan belge dosyasındaki öğe adına üye değiştirir.
• URL , harici bir kaynağa yapılan bir referanstır.
• Langword bir şekilde öne çıkarılması gereken bir kelimedir.

Örnek:

public class Point
{
    /// <summary>
    /// This method changes the point's location to
    /// the given coordinates. <see cref="Translate"/>
    /// </summary>
    public void Move(int xPosition, int yPosition)
    {
        ...
    }
    /// <summary>This method changes the point's location by
    /// the given x- and y-offsets. <see cref="Move"/>
    /// </summary>
    public void Translate(int dx, int dy)
    {
        ...
    }
}

D.3.15 <ayrıca bkz.>

Bu etiket, Ayrıca Bkz . alt maddesi için bir girdi oluşturulmasına izin verir. Metin içinden bir bağlantı belirtmek için (<see>) kullanın .

Sözdizimi:

<seealso cref=" üye" href="URL" />

nerede

• Üye , bir üyenin adıdır. Belge oluşturucu, verilen kod öğesinin var olup olmadığını kontrol eder ve oluşturulan belge dosyasındaki öğe adına üye değiştirir.
• URL , harici bir kaynağa yapılan bir referanstır.

Örnek:

public class Point
{
    /// <summary>
    /// This method determines whether two Points have the same location.
    /// </summary>
    /// <seealso cref="operator=="/>
    /// <seealso cref="operator!="/>
    public override bool Equals(object o)
    {
        ...
    }
}

D.3.16 <Özet>

Bu etiket, bir türü veya bir türün üyesini tanımlamak için kullanılabilir. (<remarks>§D.3.12) kullanarak tür veya üye hakkında ek bilgi belirtin.

Sözdizimi:

<summary> Açıklama</summary>

nerede

• Açıklama , türün veya üyenin bir özetidir.

Örnek:

public class Point
{

    /// <summary>
    /// This constructor initializes the new Point to
    /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
    /// </summary>
    public Point(int xPosition, int yPosition) 
    {
        ...
    }

    /// <summary>This constructor initializes the new Point to (0,0).</summary>
    public Point() : this(0, 0)
    {
    }
}

D.3.17 <tür parametresi>

Bu etiket, genel bir tür veya yöntem için bir tür parametresini tanımlamak için kullanılır.

Sözdizimi:

<typeparam name=" ad">Açıklama</typeparam>

nerede

• name , type parametresinin adıdır.
• description , type parametresinin bir açıklamasıdır.

Örnek:

/// <summary>A generic list class.</summary>
/// <typeparam name="T">The type stored by the list.</typeparam>
public class MyList<T>
{
   ...
}

D.3.18 <typeparamref>

Bu etiket, bir sözcüğün bir tür parametresi olduğunu belirtmek için kullanılır. Belge dosyası, bu tür parametreyi farklı bir şekilde biçimlendirmek için işlenebilir.

Sözdizimi:

<typeparamref name=" ad"/>

nerede

• name , type parametresinin adıdır.

Örnek:

public class MyClass
{
    /// <summary>
    /// This method fetches data and returns a list of
    /// <typeparamref name="T"/>.
    /// </summary>
    /// <param name="query">query to execute</param>
    public List<T> FetchData<T>(string query)
    {
        ...
    }
}

D.3.19 <değeri>

Bu etiket, bir özelliğin tanımlanmasını sağlar.

Sözdizimi:

<value> Emlak açıklaması</value>

nerede

• Mülk açıklaması , mülk için bir açıklamadır.

Örnek:

public class Point
{
    /// <value>Property <c>X</c> represents the point's x-coordinate.</value>
    public int X { get; set; }
}

D.4 Dokümantasyon dosyasının işlenmesi

D.4.1 Genel

Aşağıdaki bilgiler, CLI'yi hedefleyen C# uygulamalarına yöneliktir.

Belge oluşturucu, kaynak kodundaki her öğe için bir belge açıklamasıyla etiketlenmiş bir kimlik dizesi oluşturur. Bu kimlik dizesi, bir kaynak öğeyi benzersiz bir şekilde tanımlar. Belge görüntüleyicisi, belgelerin uygulandığı ilgili öğeyi tanımlamak için bir kimlik dizesi kullanabilir.

Dokümantasyon dosyası, kaynak kodun hiyerarşik bir temsili değildir; bunun yerine, her öğe için oluşturulmuş bir kimlik dizesine sahip düz bir listedir.

D.4.2 Kimlik dizesi biçimi

Belge oluşturucu, kimlik dizelerini oluştururken aşağıdaki kurallara uyar:

• Dizede boşluk bulunmuyor.

• Dizenin ilk kısmı, tek bir karakter ve ardından iki nokta üst üste aracılığıyla belgelenen üye türünü tanımlar. Aşağıdaki üye türleri tanımlanmıştır:

  Karakter	Açıklama
  E	Etkinlik
  F	Alan
  M	Yöntem (oluşturucular, sonlandırıcılar ve işleçler dahil)
  N	Namespace
  P	Özellik (dizin oluşturucular dahil)
  T	Tür (sınıf, temsilci, sabit listesi, arabirim ve yapı gibi)
  !	Hata dizesi; Dizenin geri kalanı hata hakkında bilgi sağlar. Örneğin, belge oluşturucu çözümlenemeyen 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ı, çevreleyen türleri ve ad alanı noktalarla ayrılır. Öğenin adında noktalar varsa, bunlar # (U+0023) karakterleriyle değiştirilir. (Hiçbir öğenin adında bu karakterin bulunmadığı varsayılmaktadır.) Bir üye genel arabirimin bir üyesini açıkça uyguladığında, tam nitelikli addaki bağımsız değişkenleri yazın, bunları çevreleyen "<" ve "" karakterleri "" ve ">{" karakterleriyle} değiştirilerek kodlanır.

• Bağımsız değişkenleri olan yöntemler ve özellikler için, parantez içine alınmış bağımsız değişken listesi aşağıdaki gibidir. Argümanı olmayanlar için parantezler atlanır. Bağımsız değişkenler virgülle ayrılır. Her bağımsız değişkenin kodlaması, aşağıdaki gibi bir CLI imzasıyla aynıdır:

  • Bağımsız değişkenler, tam nitelikli adlarına dayanan ve aşağıdaki gibi değiştirilen belge adlarıyla temsil edilir:
    • Genel türleri temsil eden bağımsız değişkenlerin sonuna bir "'" karakteri eklenir ve ardından tür parametrelerinin sayısı gelir
    • , in veya out değiştiricisine sahip bağımsız değişkenlerin reftür adlarından sonra gelen bir @ ad vardır. Değere veya üzerinden params iletilen bağımsız değişkenlerin özel bir gösterimi yoktur.
    • Diziler olan bağımsız değişkenler [: olarak , temsil edilir ... , alt sınır:boyut] burada virgül sayısı bir derece eksiktir ve biliniyorsa her boyutun alt sınırları ve boyutu ondalık olarak temsil edilir. Daha düşük bir sınır veya boyut belirtilmezse, atlanır. Belirli bir boyut için alt sınır ve boyut atlanırsa, ":" işareti de atlanır. Pürüzlü diziler, seviye başına bir "[]" ile temsil edilir. Tek boyutlu diziler, alt sınır 0 (varsayılan) olduğunda alt sınırı atlar (§17.1).
    • Dışında void işaretçi türlerine sahip bağımsız değişkenler, aşağıdaki tür adı kullanılarak * temsil edilir. Bir void işaretçi, .System.Void
    • Türlerde tanımlanan genel tür parametrelerine başvuran bağımsız değişkenler, "`" karakteri ve ardından tür parametresinin sıfır tabanlı dizini kullanılarak kodlanır.
    • Yöntemlerde tanımlanan genel tür parametrelerini kullanan bağımsız değişkenler, türler için kullanılan "``" yerine çift ters onay işareti "`" kullanır.
    • Oluşturulan genel türlere başvuran bağımsız değişkenler, genel tür kullanılarak kodlanır, ardından "{" gelir, ardından virgülle ayrılmış tür bağımsız değişkenleri listesi ve ardından "}" gelir.

D.4.3 Kimlik dizesi örnekleri

Aşağıdaki örneklerin her biri, bir belge açıklamasına sahip olabilen her kaynak öğeden üretilen kimlik dizesiyle birlikte C# kodunun bir parçasını gösterir:

Türler , genel bilgilerle zenginleştirilmiş tam nitelikli adları kullanılarak temsil edilir:

enum Color { Red, Blue, Green }

namespace Acme
{
    interface IProcess { ... }

    struct ValueType { ... }

    class Widget : IProcess
    {
        public class NestedClass { ... }
        public interface IMenuItem { ... }
        public delegate void Del(int i);
        public enum Direction { North, South, East, West }
    }

    class MyList<T>
    {
        class Helper<U,V> { ... }
    }
}

Kimlik:

"T:Color"
"T:Acme.IProcess"
"T:Acme.ValueType"
"T:Acme.Widget"
"T:Acme.Widget.NestedClass"
"T:Acme.Widget.IMenuItem"
"T:Acme.Widget.Del"
"T:Acme.Widget.Direction"
"T:Acme.MyList`1"
"T:Acme.MyList`1.Helper`2"

Alanlar , tam adlarıyla temsil edilir.

namespace Acme
{
    struct ValueType
    {
        private int total;
    }

    class Widget : IProcess
    {
        public class NestedClass
        {
            private int value;
        }

        private string message;
        private static Color defaultColor;
        private const double PI = 3.14159;
        protected readonly double monthlyAverage;
        private long[] array1;
        private Widget[,] array2;
        private unsafe int *pCount;
        private unsafe float **ppValues;
    }
}

Kimlik:

"F:Acme.ValueType.total"
"F:Acme.Widget.NestedClass.value"
"F:Acme.Widget.message"
"F:Acme.Widget.defaultColor"
"F:Acme.Widget.PI"
"F:Acme.Widget.monthlyAverage"
"F:Acme.Widget.array1"
"F:Acme.Widget.array2"
"F:Acme.Widget.pCount"
"F:Acme.Widget.ppValues"

Yapıcılar

namespace Acme
{
    class Widget : IProcess
    {
        static Widget() { ... }
        public Widget() { ... }
        public Widget(string s) { ... }
    }
}

Kimlik:

"M:Acme.Widget.#cctor"
"M:Acme.Widget.#ctor"
"M:Acme.Widget.#ctor(System.String)"

Sonlandırıcılar

namespace Acme
{
    class Widget : IProcess
    {
        ~Widget() { ... }
    }
}

Kimlik:

"M:Acme.Widget.Finalize"

Yöntemler

namespace Acme
{
    struct ValueType
    {
        public void M(int i) { ... }
    }

    class Widget : IProcess
    {
        public class NestedClass
        {
            public void M(int i) { ... }
        }

        public static void M0() { ... }
        public void M1(char c, out float f, ref ValueType v, in int i) { ... }
        public void M2(short[] x1, int[,] x2, long[][] x3) { ... }
        public void M3(long[][] x3, Widget[][,,] x4) { ... }
        public unsafe void M4(char *pc, Color **pf) { ... }
        public unsafe void M5(void *pv, double *[][,] pd) { ... }
        public void M6(int i, params object[] args) { ... }
    }

    class MyList<T>
    {
        public void Test(T t) { ... }
    }

    class UseList
    {
        public void Process(MyList<int> list) { ... }
        public MyList<T> GetValues<T>(T value) { ... } 
    }
}

Kimlik:

"M:Acme.ValueType.M(System.Int32)"
"M:Acme.Widget.NestedClass.M(System.Int32)"
"M:Acme.Widget.M0"
"M:Acme.Widget.M1(System.Char,System.Single@,Acme.ValueType@,System.Int32@)"
"M:Acme.Widget.M2(System.Int16[],System.Int32[0:,0:],System.Int64[][])"
"M:Acme.Widget.M3(System.Int64[][],Acme.Widget[0:,0:,0:][])"
"M:Acme.Widget.M4(System.Char*,Color**)"
"M:Acme.Widget.M5(System.Void*,System.Double*[0:,0:][])"
"M:Acme.Widget.M6(System.Int32,System.Object[])"
"M:Acme.MyList`1.Test(`0)"
"M:Acme.UseList.Process(Acme.MyList{System.Int32})"
"M:Acme.UseList.GetValues``1(``0)"

Özellikler ve dizin oluşturucular

namespace Acme
{
    class Widget : IProcess
    {
        public int Width { get { ... } set { ... } }
        public int this[int i] { get { ... } set { ... } }
        public int this[string s, int i] { get { ... } set { ... } }
    }
}

Kimlik:

"P:Acme.Widget.Width"
"P:Acme.Widget.Item(System.Int32)"
"P:Acme.Widget.Item(System.String,System.Int32)"

Etkinlikler

namespace Acme
{
    class Widget : IProcess
    {
        public event Del AnEvent;
    }
}

Kimlik:

"E:Acme.Widget.AnEvent"

Birli operatörler

namespace Acme
{
    class Widget : IProcess
    {
        public static Widget operator+(Widget x) { ... }
    }
}

Kimlik:

"M:Acme.Widget.op_UnaryPlus(Acme.Widget)"

Kullanılan tekli işleç işlev adlarının tam kümesi aşağıdaki gibidir: op_UnaryPlus, op_UnaryNegation, op_LogicalNotop_OnesComplementop_Incrementop_Decrementop_Trueve .op_False

İkili operatörler

namespace Acme
{
    class Widget : IProcess
    {
        public static Widget operator+(Widget x1, Widget x2) { ... }
    }
}

Kimlik:

"M:Acme.Widget.op_Addition(Acme.Widget,Acme.Widget)"

Kullanılan ikili işleç işlev adlarının tam kümesi aşağıdaki gibidir: op_Addition, , op_Subtractionop_Multiplyop_Divisionop_Modulusop_BitwiseAndop_BitwiseOrop_ExclusiveOrop_LeftShiftop_RightShiftop_Equalityop_Inequalityop_LessThanop_LessThanOrEqualop_GreaterThanop_GreaterThanOrEqual

Dönüştürme operatörlerinin sonunda bir "~" bulunur ve ardından dönüş türü gelir. Bir dönüştürme operatörünün kaynağı veya hedefi genel bir türse, "<" ve "">" karakterleri sırasıyla "{" ve "}" karakterleriyle değiştirilir.

namespace Acme
{
    class Widget : IProcess
    {
        public static explicit operator int(Widget x) { ... }
        public static implicit operator long(Widget x) { ... }
    }
}

Kimlik:

"M:Acme.Widget.op_Explicit(Acme.Widget)~System.Int32"
"M:Acme.Widget.op_Implicit(Acme.Widget)~System.Int64"

D.5 Bir örnek

D.5.1 C# kaynak kodu

Aşağıdaki örnek, bir Point sınıfının kaynak kodunu gösterir:

namespace Graphics
{
    /// <summary>
    /// Class <c>Point</c> models a point in a two-dimensional plane.
    /// </summary>
    public class Point
    {
        /// <value>
        /// Property <c>X</c> represents the point's x-coordinate.
        /// </value>
        public int X { get; set; }
        
        /// <value>
        /// Property <c>Y</c> represents the point's y-coordinate.
        /// </value>
        public int Y { get; set; }
        
        /// <summary>
        /// This constructor initializes the new Point to (0,0).
        /// </summary>
        public Point() : this(0, 0) {}
        
        /// <summary>
        /// This constructor initializes the new Point to
        /// (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
        /// </summary>
        /// <param name="xPosition">The new Point's x-coordinate.</param>
        /// <param name="yPosition">The new Point's y-coordinate.</param>
        public Point(int xPosition, int yPosition) 
        {
            X = xPosition;
            Y = yPosition;
        }
        
        /// <summary>
        /// This method changes the point's location to
        /// the given coordinates. <see cref="Translate"/>
        /// </summary>
        /// <param name="xPosition">The new x-coordinate.</param>
        /// <param name="yPosition">The new y-coordinate.</param>
        public void Move(int xPosition, int yPosition) 
        {
            X = xPosition;
            Y = yPosition;
        }
        
        /// <summary>
        /// This method changes the point's location by
        /// the given x- and y-offsets.
        /// <example>For example:
        /// <code>
        /// Point p = new Point(3, 5);
        /// p.Translate(-1, 3);
        /// </code>
        /// results in <c>p</c>'s having the value (2, 8).
        /// <see cref="Move"/>
        /// </example>
        /// </summary>
        /// <param name="dx">The relative x-offset.</param>
        /// <param name="dy">The relative y-offset.</param>
        public void Translate(int dx, int dy)
        {
            X += dx;
            Y += dy;
        }
        
        /// <summary>
        /// This method determines whether two Points have the same location.
        /// </summary>
        /// <param name="o">
        /// The object to be compared to the current object.
        /// </param>
        /// <returns>
        /// True if the Points have the same location and they have
        /// the exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="operator=="/>
        /// <seealso cref="operator!="/>
        public override bool Equals(object o)
        {
            if (o == null)
            {
                return false;
            }
            if ((object)this == o) 
            {
                return true;
            }
            if (GetType() == o.GetType()) 
            {
                Point p = (Point)o;
                return (X == p.X) && (Y == p.Y);
            }
            return false;
        }

        /// <summary>
        /// This method returns a Point's hashcode.
        /// </summary>
        /// <returns>
        /// The int hashcode.
        /// </returns>
        public override int GetHashCode()
        {
            return X + (Y >> 4);    // a crude version
        }
        
        /// <summary>Report a point's location as a string.</summary>
        /// <returns>
        /// A string representing a point's location, in the form (x,y),
        /// without any leading, training, or embedded whitespace.
        /// </returns>
        public override string ToString() => $"({X},{Y})";
        
        /// <summary>
        /// This operator determines whether two Points have the same location.
        /// </summary>
        /// <param name="p1">The first Point to be compared.</param>
        /// <param name="p2">The second Point to be compared.</param>
        /// <returns>
        /// True if the Points have the same location and they have
        /// the exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="Equals"/>
        /// <seealso cref="operator!="/>
        public static bool operator==(Point p1, Point p2)
        {
            if ((object)p1 == null || (object)p2 == null)
            {
                return false;
            }
            if (p1.GetType() == p2.GetType())
            {
                return (p1.X == p2.X) && (p1.Y == p2.Y);
            }
            return false;
        }
        
        /// <summary>
        /// This operator determines whether two Points have the same location.
        /// </summary>
        /// <param name="p1">The first Point to be compared.</param>
        /// <param name="p2">The second Point to be compared.</param>
        /// <returns>
        /// True if the Points do not have the same location and the
        /// exact same type; otherwise, false.
        /// </returns>
        /// <seealso cref="Equals"/>
        /// <seealso cref="operator=="/>
        public static bool operator!=(Point p1, Point p2) => !(p1 == p2);
    }
}

D.5.2 Elde Edilen XML

Yukarıda gösterilen sınıf Pointiçin kaynak kodu verildiğinde bir dokümantasyon oluşturucu tarafından üretilen çıktı şu şekildedir:

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>Point</name>
  </assembly>
  <members>
    <member name="T:Graphics.Point">
    <summary>Class <c>Point</c> models a point in a two-dimensional
    plane.
    </summary>
    </member>
    <member name="M:Graphics.Point.#ctor">
      <summary>This constructor initializes the new Point to (0, 0).</summary>
    </member>
    <member name="M:Graphics.Point.#ctor(System.Int32,System.Int32)">
      <summary>
        This constructor initializes the new Point to
        (<paramref name="xPosition"/>,<paramref name="yPosition"/>).
      </summary>
      <param name="xPosition">The new Point's x-coordinate.</param>
      <param name="yPosition">The new Point's y-coordinate.</param>
    </member>
    <member name="M:Graphics.Point.Move(System.Int32,System.Int32)">
      <summary>
        This method changes the point's location to
        the given coordinates.
        <see cref="M:Graphics.Point.Translate(System.Int32,System.Int32)"/>
      </summary>
      <param name="xPosition">The new x-coordinate.</param>
      <param name="yPosition">The new y-coordinate.</param>
      </member>
    <member name="M:Graphics.Point.Translate(System.Int32,System.Int32)">
      <summary>
        This method changes the point's location by
        the given x- and y-offsets.
        <example>For example:
        <code>
        Point p = new Point(3,5);
        p.Translate(-1,3);
        </code>
        results in <c>p</c>'s having the value (2,8).
        </example>
        <see cref="M:Graphics.Point.Move(System.Int32,System.Int32)"/>
      </summary>
      <param name="dx">The relative x-offset.</param>
      <param name="dy">The relative y-offset.</param>
    </member>
    <member name="M:Graphics.Point.Equals(System.Object)">
      <summary>
        This method determines whether two Points have the same location.
      </summary>
      <param name="o">
        The object to be compared to the current object.
      </param>
      <returns>
        True if the Points have the same location and they have
        the exact same type; otherwise, false.
      </returns>
      <seealso 
        cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)" />
      <seealso 
        cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
    </member>
     <member name="M:Graphics.Point.ToString">
      <summary>
        Report a point's location as a string.
      </summary>
      <returns>
        A string representing a point's location, in the form (x,y),
        without any leading, training, or embedded whitespace.
      </returns>
     </member>
    <member name="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)">
      <summary>
        This operator determines whether two Points have the same location.
      </summary>
      <param name="p1">The first Point to be compared.</param>
      <param name="p2">The second Point to be compared.</param>
      <returns>
        True if the Points have the same location and they have
        the exact same type; otherwise, false.
      </returns>
      <seealso cref="M:Graphics.Point.Equals(System.Object)"/>
      <seealso
        cref="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)"/>
    </member>
    <member
        name="M:Graphics.Point.op_Inequality(Graphics.Point,Graphics.Point)">
      <summary>
        This operator determines whether two Points have the same location.
      </summary>
      <param name="p1">The first Point to be compared.</param>
      <param name="p2">The second Point to be compared.</param>
      <returns>
        True if the Points do not have the same location and the
        exact same type; otherwise, false.
      </returns>
      <seealso cref="M:Graphics.Point.Equals(System.Object)"/>
      <seealso
        cref="M:Graphics.Point.op_Equality(Graphics.Point,Graphics.Point)"/>
      </member>
      <member name="M:Graphics.Point.Main">
        <summary>
          This is the entry point of the Point class testing program.
          <para>
            This program tests each method and operator, and
            is intended to be run after any non-trivial maintenance has
            been performed on the Point class.
          </para>
        </summary>
      </member>
      <member name="P:Graphics.Point.X">
        <value>
          Property <c>X</c> represents the point's x-coordinate.
        </value>
      </member>
      <member name="P:Graphics.Point.Y">
        <value>
          Property <c>Y</c> represents the point's y-coordinate.
        </value>
    </member>
  </members>
</doc>

Bilgilendirici metnin sonu.