Belge Açıklamaları

Belge açıklamaları, kaynakta özel olarak biçimlendirilmiş ve ekli oldukları kodla ilgili belgeler üretmek üzere analiz edilebilen açıklamalardır. Belge açıklamalarının temel biçimi XML'dir. Belge açıklamalarıyla kod derlendiğinde, derleyici isteğe bağlı olarak kaynaktaki belge açıklamalarının toplamını temsil eden bir XML dosyası yayabilir. Bu XML dosyası daha sonra diğer araçlar tarafından basılı veya çevrimiçi belgeler üretmek için kullanılabilir.

Bu bölümde, belge açıklamaları ve belge açıklamalarıyla kullanılması önerilen XML etiketleri açıklanmaktadır.

Belge Açıklama Biçimi

Belge açıklamaları, ile '''başlayan, üç tek tırnak işareti olan özel açıklamalardır. Belgeledikleri tür (sınıf, temsilci veya arabirim gibi) veya tür üyesinden (alan, olay, özellik veya yöntem gibi) hemen önce gelir. Kısmi yöntem bildirimindeki belge açıklaması, varsa gövdesini sağlayan yöntemdeki belge açıklamasıyla değiştirilir. Tek bir belge açıklaması oluşturmak için tüm bitişik belge açıklamaları birlikte eklenir. Karakterleri izleyen ''' bir boşluk karakteri varsa, bu boşluk karakteri birleştirmeye dahil değildir. Örneğin:

''' <remarks>
''' Class <c>Point</c> models a point in a two-dimensional plane.
''' </remarks>
Public Class Point 
   ''' <remarks>
   ''' Method <c>Draw</c> renders the point.
   ''' </remarks>
   Sub Draw()
   End Sub
End Class

Belge açıklamaları uygun https://www.w3.org/TR/REC-xmlşekilde biçimlendirilmiş XML olmalıdır. XML iyi biçimlendirilmemişse bir uyarı oluşturulur ve belge dosyasında hatayla karşılaşıldığını belirten bir açıklama bulunur.

Geliştiriciler kendi etiket kümelerini oluşturmakta özgür olsalar da, bir sonraki bölümde önerilen bir küme tanımlanır. Önerilen etiketlerden bazılarının özel anlamları vardır:

<param> etiketi, parametreleri açıklamak için kullanılır. Bir <param> etiket tarafından belirtilen parametre bulunmalıdır ve tür üyesinin tüm parametreleri belge açıklamasında açıklanmalıdır. İki koşuldan biri doğru değilse, derleyici bir uyarı görüntüler.
Özniteliği cref , bir kod öğesine başvuru sağlamak için herhangi bir etikete eklenebilir. Kod öğesi mevcut olmalıdır; derleme zamanında derleyici adı, üyeyi temsil eden kimlik dizesiyle değiştirir. Kod öğesi yoksa, derleyici bir uyarı döndürür. Bir öznitelikte cref açıklanan bir ad ararken, derleyici, içeren kaynak dosya içinde görünen deyimlere saygı Imports gösterir.
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.

Belge dosyasının bir tür ve üyeler hakkında tam bilgi sağlamadığını, yalnızca belge açıklamalarında bulunanları sağladığını unutmayın. Bir tür veya üye hakkında daha fazla bilgi edinmek için, belge dosyasının gerçek tür veya üyedeki yansımayla birlikte kullanılması gerekir.

Önerilen etiketler

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şlevleri sağlar:

<c> Kod benzeri bir yazı tipindeki metni ayarlar

<code> Kod benzeri bir yazı tipinde bir veya daha fazla kaynak kod satırı veya program çıktısı ayarlar

<example> Bir örneği gösterir

<exception> Bir yöntemin oluşturabileceği özel durumları tanımlar

<include> Dış XML belgesi içerir

<list> Liste veya tablo oluşturur

<para> Metne yapı eklenmesine izin verir

<param> Bir yöntem veya oluşturucu için parametreyi açıklar

<paramref> Bir sözcüğün parametre adı olduğunu tanımlar

<permission> Bir üyenin güvenlik erişilebilirliğini belgeler

<remarks> Bir türü açıklar

<returns> Bir yöntemin dönüş değerini açıklar

<see> Bağlantı belirtir

<seealso> Ayrıca Bkz. girdisi oluşturur

<summary> Bir türün üyesini açıklar

<typeparam> Tür parametresini açıklar

<value> Bir özelliği açıklar

<c>

Bu etiket, açıklama içindeki bir metin parçasının kod bloğu için kullanılana benzer bir yazı tipi kullanması gerektiğini belirtir. (Gerçek kod satırları için kullanın <code>.)

Syntax:

<c>text to be set like code</c>

Örnek:

''' <remarks>
''' Class <c>Point</c> models a point in a two-dimensional plane.
''' </remarks>
Public Class Point 
End Class

<kod>

Bu etiket, bir veya daha fazla kaynak kodu satırı veya program çıktısının sabit genişlikli bir yazı tipi kullanması gerektiğini belirtir. (Küçük kod parçaları için kullanın <c>.)

Syntax:

<code>source code or program output</code>

Örnek:

''' <summary>
''' This method changes the point's location by the given x- and 
''' y-offsets.
''' <example>
''' For example:
''' <code>
'''    Dim p As Point = New Point(3,5)
'''    p.Translate(-1,3)
''' </code>
''' results in <c>p</c>'s having the value (2,8).
''' </example>
''' </summary>
Public Sub Translate(x As Integer, y As Integer)
    Me.x += x
    Me.y += y
End Sub

<örnek>

Bu etiket, açıklama içindeki örnek kodun bir öğenin nasıl kullanılabileceğini göstermesine olanak tanır. Normalde, bu etiket <code> kullanımını da içerir.

Syntax:

<example>description</example>

Örnek:

Örnek için bkz <code> .

<istisna>

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

Syntax:

<exception cref="member">description</exception>

Örnek:

Public Module DataBaseOperations
    ''' <exception cref="MasterFileFormatCorruptException"></exception>
    ''' <exception cref="MasterFileLockedOpenException"></exception>
    Public Sub ReadRecord(flag As Integer)
        If Flag = 1 Then
            Throw New MasterFileFormatCorruptException()
        ElseIf Flag = 2 Then
            Throw New MasterFileLockedOpenException()
        End If
        ' ...
    End Sub
End Module

<dahil etme>

Bu etiket, iyi biçimlendirilmiş bir dış XML belgesinden bilgi eklemek için kullanılır. Belgeden hangi XML'nin eklenmesi gerektiğini belirtmek için XML belgesine bir XPath ifadesi uygulanır. Etiket <include> daha sonra harici belgeden seçilen XML ile değiştirilir.

Syntax:

<include file="filename" path="xpath">

Örnek:

Kaynak kodu aşağıdaki gibi bir bildirim içeriyorsa:

''' <include file="docs.xml" path="extra/class[@name="IntList"]/*" />

ve dış dosya docs.xml aşağıdaki içeriklere sahipti

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

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

''' <summary>
''' Contains a list of integers.
''' </summary>

<listele>

Bu etiket, bir öğe listesi veya tablosu oluşturmak için kullanılır. Tablo veya tanım listesinin başlık satırını tanımlamak için bir blok içerebilir <listheader> . (Tablo tanımlarken, yalnızca başlıktaki terim için bir girdi sağlanmalıdır.)

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

Syntax:

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

Örnek:

Public Class TestClass
    ''' <remarks>
    ''' Here is an example of a bulleted list:
    ''' <list type="bullet">
    '''     <item>
    '''        <description>Item 1.</description>
    '''     </item>
    '''     <item>
    '''         <description>Item 2.</description>
    '''     </item>
    ''' </list>
    ''' </remarks>
    Public Shared Sub Main()
    End Sub
End Class

<paragraf>

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

Syntax:

<para>content</para>

Örnek:

''' <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-trvial maintenance has
''' been performed on the Point class.</para>
''' </summary>
Public Shared Sub Main()
End Sub

<param>

Bu etiket bir yöntem, oluşturucu veya dizine alınan özelliğin parametresini açıklar.

Syntax:

<param name="name">description</param>

Örnek:

''' <summary>
''' This method changes the point's location to the given
''' coordinates.
''' </summary>
''' <param name="x"><c>x</c> is the new x-coordinate.</param>
''' <param name="y"><c>y</c> is the new y-coordinate.</param>
Public Sub Move(x As Integer, y As Integer)
    Me.x = x
    Me.y = y
End Sub

<paramref>

Bu etiket, bir sözcüğün parametre olduğunu gösterir. Dokümantasyon dosyası, bu parametreyi farklı bir şekilde biçimlendirmek için işlenebilir.

Syntax:

<paramref name="name"/>

Örnek:

''' <summary>
''' This constructor initializes the new Point to
''' (<paramref name="x"/>,<paramref name="y"/>).
''' </summary>
''' <param name="x"><c>x</c> is the new Point's x-coordinate.</param>
''' <param name="y"><c>y</c> is the new Point's y-coordinate.</param>
Public Sub New(x As Integer, y As Integer)
    Me.x = x
    Me.y = y
End Sub

<izin>

Bu etiket, bir üyenin güvenlik erişilebilirliğini belgeler

Syntax:

<permission cref="member">description</permission>

Örnek:

''' <permission cref="System.Security.PermissionSet">Everyone can
''' access this method.</permission>
Public Shared Sub Test()
End Sub

<Açıklamalar>

Bu etiket, bir türle ilgili genel bakış bilgilerini belirtir. (Bir türün üyelerini açıklamak için kullanın <summary> .)

Syntax:

<remarks>description</remarks>

Örnek:

''' <remarks>
''' Class <c>Point</c> models a point in a two-dimensional plane.
''' </remarks>
Public Class Point 
End Class

<Döndürür>

Bu etiket bir yöntemin dönüş değerini açıklar.

Syntax:

<returns>description</returns>

Örnek:

''' <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 Overrides Function ToString() As String
    Return "(" & x & "," & y & ")"
End Sub

<görmek>

Bu etiket, metin içinde bir bağlantının belirtilmesini sağlar. (Ayrıca Bkz. bölümünde görüntülenecek metni belirtmek için kullanın <seealso> .)

Syntax:

<see cref="member"/>

Örnek:

''' <summary>
''' This method changes the point's location to the given
''' coordinates.
''' </summary>
''' <see cref="Translate"/>
Public Sub Move(x As Integer, y As Integer)
    Me.x = x
    Me.y = y
End Sub

''' <summary>
''' This method changes the point's location by the given x- and
''' y-offsets.
''' </summary>
''' <see cref="Move"/>
Public Sub Translate(x As Integer, y As Integer)
    Me.x += x
    Me.y += y
End Sub

<bakınız>

Bu etiket Ayrıca Bkz bölümü için bir girdi oluşturur. (Metnin içinden bir bağlantı belirtmek için kullanın <see> .)

Syntax:

<seealso cref="member"/>

Örnek:

''' <summary>
''' This method determines whether two Points have the same location.
''' </summary>
''' <seealso cref="operator=="/>
''' <seealso cref="operator!="/>
Public Overrides Function Equals(o As Object) As Boolean
    ' ...
End Function

<özet>

Bu etiket bir tür üyesini açıklar. (Bir türün kendisini tanımlamak için kullanın <remarks> .)

Syntax:

<summary>description</summary>

Örnek:

''' <summary>
''' This constructor initializes the new Point to (0,0).
''' </summary>
Public Sub New()
    Me.New(0,0)
End Sub

<typeparam>

Bu etiket bir tür parametresini açıklar.

Syntax:

<typeparam name="name">description</typeparam>

Örnek:

''' <typeparam name="T">
''' The base item type. Must implement IComparable.
''' </typeparam>
Public Class ItemManager(Of T As IComparable)
End Class

<değer>

Bu etiket bir özelliği açıklar.

Syntax:

<value>property description</value>

Örnek:

''' <value>
''' Property <c>X</c> represents the point's x-coordinate.
''' </value>
Public Property X() As Integer
    Get
        Return _x
    End Get
    Set (Value As Integer)
        _x = Value
    End Set
End Property

Kimlik Dizeleri

Belge dosyasını oluştururken, derleyici kaynak koddaki her öğe için benzersiz olarak tanımlayan bir belge açıklamasıyla etiketlenmiş bir kimlik dizesi oluşturur. Bu kimlik dizesi, derlenmiş derlemedeki hangi öğenin belge açıklamasına karşılık olduğunu belirlemek için dış araçlar tarafından kullanılabilir.

Kimlik dizeleri aşağıdaki gibi oluşturulur:

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, bundan sonra parantez içinde karşılık gelen karakterle tanımlanır: olaylar (E), alanlar (F), oluşturucular ve işleçler (M), ad alanları (N), özellikler (P) ve türler (T) gibi yöntemler. Ünlem işareti (!) kimlik dizesi oluşturulurken bir hata oluştuğuna işaret eder ve dizenin geri kalanı hata hakkında bilgi sağlar.

Dizenin ikinci bölümü, genel ad alanında başlayarak öğesinin tam adıdır. Öğesinin adı, kapsayan türleri ve ad alanı noktalarla ayrılır. Öğenin adının dönemleri varsa, bunlar pound işareti (#) ile değiştirilir. (Hiçbir öğenin adında bu karakter olmadığı varsayılır.) Tür parametrelerine sahip bir türün adı bir ters alıntı (') ile biter ve ardından türdeki tür parametrelerinin sayısını gösteren bir sayı olur. İç içe türlerin bunları içeren türlerin tür parametrelerine erişimi olduğundan, iç içe türlerin örtük olarak bunları içeren türlerin tür parametrelerini içerdiğini ve bu türlerin bu durumda tür parametre toplamlarında sayıldığını unutmayın.

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ı cli imzası ile aynıdır, aşağıdaki gibi: Bağımsız değişkenler tam adlarıyla temsil edilir. Örneğin, olurSystem.Int32, IntegerString olurSystem.String, Object olur, vb. olurSystem.Object. Değiştiriciye sahip bağımsız değişkenlerin ByRef tür adlarını izleyen bir '@' değeri vardır. veya OptionalParamArray değiştiricisine sahip bağımsız değişkenlerin ByValözel gösterimi yoktur. Dizi [lowerbound:size, ..., lowerbound:size] olan bağımsız değişkenler, virgül sayısının derece - 1 olduğu ve her boyutun alt sınırları ve boyutu (biliniyorsa) 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, ':' da atlanır. Dizi dizileri düzey başına bir "[]" ile temsil edilir.

Kimlik dizesi örnekleri

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

Türler, tam adları kullanılarak temsil edilir.

Enum Color
    Red
    Blue
    Green
End Enum

Namespace Acme
    Interface IProcess
    End Interface

    Structure ValueType
        ...
    End Structure

    Class Widget
        Public Class NestedClass
        End Class

        Public Interface IMenuItem
        End Interface

        Public Delegate Sub Del(i As Integer)

        Public Enum Direction
            North
            South
            East
            West
        End Enum
    End Class
End Namespace

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

Alanlar, tam adlarıyla temsil edilir.

Namespace Acme
    Structure ValueType
        Private total As Integer
    End Structure

    Class Widget
        Public Class NestedClass
            Private value As Integer
        End Class

        Private message As String
        Private Shared defaultColor As Color
        Private Const PI As Double = 3.14159
        Protected ReadOnly monthlyAverage As Double
        Private array1() As Long
        Private array2(,) As Widget
    End Class
End Namespace

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

Kurucular.

Namespace Acme
    Class Widget
        Shared Sub New()
        End Sub

        Public Sub New()
        End Sub

        Public Sub New(s As String)
        End Sub
    End Class
End Namespace

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

Yöntemler.

Namespace Acme
    Structure ValueType
        Public Sub M(i As Integer)
        End Sub
    End Structure

    Class Widget
        Public Class NestedClass
            Public Sub M(i As Integer)
            End Sub
        End Class

        Public Shared Sub M0()
        End Sub

        Public Sub M1(c As Char, ByRef f As Float, _
            ByRef v As ValueType)
        End Sub

        Public Sub M2(x1() As Short, x2(,) As Integer, _
            x3()() As Long)
        End Sub

        Public Sub M3(x3()() As Long, x4()(,,) As Widget)
        End Sub

        Public Sub M4(Optional i As Integer = 1)

        Public Sub M5(ParamArray args() As Object)
        End Sub
    End Class
End Namespace

"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@)"
"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.Int32)"
"M:Acme.Widget.M5(System.Object[])"

Özellikler.

Namespace Acme
    Class Widget
        Public Property Width() As Integer
            Get
            End Get
            Set (Value As Integer)
            End Set
        End Property

        Public Default Property Item(i As Integer) As Integer
            Get
            End Get
            Set (Value As Integer)
            End Set
        End Property

        Public Default Property Item(s As String, _
            i As Integer) As Integer
            Get
            End Get
            Set (Value As Integer)
            End Set
        End Property
    End Class
End Namespace

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

Etkinlikler

Namespace Acme
    Class Widget
        Public Event AnEvent As EventHandler
        Public Event AnotherEvent()
    End Class
End Namespace

"E:Acme.Widget.AnEvent"
"E:Acme.Widget.AnotherEvent"

Işleç.

Namespace Acme
    Class Widget
        Public Shared Operator +(x As Widget) As Widget
        End Operator

        Public Shared Operator +(x1 As Widget, x2 As Widget) As Widget
        End Operator
    End Class
End Namespace

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

Dönüştürme işleçlerinin sonunda ~ dönüş türü bulunur.

Namespace Acme
    Class Widget
        Public Shared Narrowing Operator CType(x As Widget) As _
            Integer
        End Operator

        Public Shared Widening Operator CType(x As Widget) As Long
        End Operator
    End Class
End Namespace

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