Visual Basic 2012 Voorbeelden
   

visual basic 2012 broncode voorbeelden

Blijf op de hoogte van de recente aanpassingen op vbvoorbeelden!

Microsoft Visual Studio 2012Microsoft Developers Network - Visual BasicMicrosoft .NET Framework

33.2. XML Documentatie Commentaar

Print Email Deel op Twitter Deel op Facebook

Dit artikel is gepubliceerd op maandag 15 oktober 2012 op vbvoorbeelden, bezoek de website voor een recente versie van dit artikel of andere artikels.

Visual Basic voorziet in een eenvoudige manier om voor een project XML reference documentatie te genereren.  Aan de hand van XML documentatie commentaar, die in de code is aangebracht, kan je bijvoorbeeld informatie voorzien over klassen, methods, parameters, return types, optredende excepties, ... .
Visual Studio : Indien in Visual Studio bij de project opties op het tabblad Compile de optie Generate XML documentation file is aangevinkt, zal bij het builden van dit project een bestand met dezelfde naam als de assembly, maar de extensie .xml worden gegenereerd.  Dit bestand, die in de output bin directory terecht komt, bevat dan de documentatie die via de XML documentation comments aan de code was toegevoegd.

Indien de commandline compiler wordt gebruikt, kan je via de schakeloptie /doc aangeven dat dit bestand wordt gegenereerd.
XML documentation comments, die in de broncode worden opgenomen, worden voorafgegaan door drie single quotes.
Visual Studio : Indien je alvast drie single quotes aanbrengt in de code zal de Visual Studio editor meteen een XML skelet voor dit type of member toevoegen.  Dit skelet bevat meteen de <summary> en <remarks> tag.
XML documentatie commentaar moet well-formed XML zijn en kan worden toegevoegd aan types en members van deze types.

Een voorbeeld :
Visual Basic 2012 Broncode - Codevoorbeeld 819
Namespace SyntaxHighlighter
   ''' <summary>Specifies the type of a <see cref="Match"/>.</summary>
   Public Enum MatchType
       ''' <summary>Used for comment matches.</summary>
       Comment
       ''' <summary>Used for stringliteral matches.</summary>
       Stringliteral
       ''' <summary>Used for keyword matches.</summary>
       Keyword
   End Enum
   ''' <summary>Represents a match in Visual Basic sourcecode.</summary>
   ''' <remarks>Examples of matches are comment, stringliteral and keyword
   ''' matches.</remarks>
   ''' <seealso cref="MatchType"/>
   ''' <seealso cref="Sourcecode"/>
   Public Class Match
       Private _Index As Integer
       Private _MatchType As MatchType
       ''' <summary>Initializes a new instance of the
       ''' SyntaxHighlighter.Match class.</summary>
       ''' <param name="matchType">Specifies the type of Match.</param>
       ''' <param name="index">Indicates the startindex of the Match.</param>
       Public Sub New(ByVal matchType As MatchType, ByVal index As Integer)
           _MatchType = matchType
           _Index = index
       End Sub
       ''' <summary>Gets the <see cref="SyntaxHighlighter.MatchType">MatchType
       ''' </see> of the Match.</summary>
       ''' <value>Represents the <see cref="SyntaxHighlighter.MatchType">
       ''' MatchType</see> of the Match.</value>
       ''' <returns>A <see cref="SyntaxHighlighter.MatchType">MatchType</see>
       ''' enumeration value.</returns>
       ''' <seealso cref="SyntaxHighlighter.MatchType" />
       Public ReadOnly Property MatchType() As MatchType
           Get
               MatchType = _MatchType
           End Get
       End Property
       ''' <summary>Gets the startindex of the Match within the
       ''' <see cref="Sourcecode"/> object.</summary>
       ''' <value>Represents the startindex of the Match within the
       ''' <see cref="Sourcecode"/> object.</value>
       ''' <returns>The startindex of the Match within the
       ''' <see cref="Sourcecode"/> object.</returns>
       ''' <seealso cref="Sourcecode" />
       Public ReadOnly Property Index() As Integer
           Get
               Index = _Index
           End Get
       End Property
       ''' <summary>Returns a System.String that represents the current Match.
       ''' </summary>
       ''' <returns>A System.String that represents the current Match object.
       ''' </returns>
       Public Overrides Function ToString() As String
           ToString = '...
       End Function
       ''' <summary>Determines whether this instance of SyntaxHighlighter.Match
       ''' and a specified object are equal.</summary>
       ''' <remarks>Equality between the two matches is based on equality
       ''' between the <see cref="Index"/> and <see cref="Value"/> properties.
       ''' </remarks>
       ''' <param name="obj">The object to compare the current Match with.
       ''' </param>
       ''' <returns><c>True</c> if <see cref="Index"/> and <see cref="Value"/>
       ''' of the current Match and <paramref name="obj"/> are equal.
       ''' Otherwise <c>False</c>.</returns>
       Public Overrides Function Equals(ByVal obj As Object) As Boolean
           If TypeOf obj Is Match Then
               Equals = Equals(DirectCast(obj, Match))
           End If
       End Function
   End Class
End Namespace

33.2.1. <summary> en <remark> Tags

Gebruik de <summary> tag om samenvattende informatie over een type of member te voorzien, bijkomende informatie kan je plaatsen in de <remarks> tag.  De <summary> tag zal voor een datatype doorgaans beschrijven wat een instantie van dit type voorstelt, <summary>Represents ...</summary>.

Voor een member plaatst men in de <summary> tag doorgaan wat deze member doet, of wat het oplevert.
Visual Studio : De documentatie in de <summary> tag wordt bijvoorbeeld ook door IntelliSense gebruikt om informatie over dit element te voorzien.

33.2.2. <c>, <code> en <example> Tags

Gebruik de <c> tag om code te omsluiten, bij meerdere regels gebruik je de <code> tag.
Gaat het om een voorbeeld dan omsluit je <code> nogmaals met een <example> tag.

Bijvoorbeeld :
''' <remarks>
''' <example>
''' This sample shows how to set the <c>Name</c> property.
''' <code language="VB">
''' Dim person1 As Person
''' person1.Name = "John"
''' </code>
''' </example>
''' </remarks>

33.2.3. <param> en <paramref> Tags

De <param> tag met name attribuut (<param name="...">) wordt gebruikt om parameters te beschrijven.  Het name attribuut geef aan welke parameter je hier documenteert.
Indien <param> voor één parameter wordt gebruikt, moet men voor alle parameters documentatie voorzien en zal de compiler verifiëren of deze parameters wel aanwezig zijn.

Element <paramref> met name attribuut (<paramref name="...">) wordt dan gebruik om elders naar deze parameter te verwijzen

33.2.4. <value> en <returns> Tags

De <value> tag gebruik je om aan te geven welke waarde een Property voorstelt.
Bij functies gebruik je de <returns> tag om de return waarde te omschrijven.

33.2.5. <see> en <seealso> Tags

Gebruik binnen beschrijvende tekst de <see> tag met cref attribuut om een link/verwijzing naar type of member te plaatsen.  Uiteraard moet dit code element dan ook effectief bestaan, en in de huidige scope beschikbaar zijn, wat de compiler zal nagaan.

Element <seealso> is indentiek met als verschil dat hierbij de link naar dit type of member hierbij ook in de "See Also" rubriek terecht komt.

33.2.6. <exception> Tag

Gebruik de <exception> tag met cref attribuut (<exception cref="...">) om aan te geven wanneer deze exceptie, waar het cref attribuut naar verwijst, te omschrijven.

Bijvoorbeeld :
''' <exception cref="System.IndexOutOfRangeException">Thrown when
'''    <paramref name="index"/> is a non-existing element index.</exception>
Public Function GetItem(ByVal index As Integer) As Object
    GetItem = _Items(index)
End Function
Visual Studio : Bemerk ook hoe in Visual Studio de Object Browser al deze beschrijvende informatie toont.
Indien je kleiner of groter dan symbolen wenst te gebruiken in de tekst van een documentation comment, gebruik dan & lt; voor < en & gt; voor >.
Voor een volledig lijst van de mogelijk tags en hoe deze worden gebruikt kan je terecht op onderstaande link :
Na het builden van bovenstaand voorbeeld bekomen we een XML documentatie bestand met volgende inhoud :
XML Instantie
<?xml version="1.0"?>
<doc>
  <assembly>
    <name>SyntaxHighlighter</name>
  </assembly>
  <members>
    <member name="M:SyntaxHighlighter.Match.#ctor(SyntaxHighlighter.MatchType,
                                                  System.Int32)">
      <summary>Initializes a new instance of the SyntaxHighlighter.Match class.
      </summary>
      <param name="matchType">Specifies the type of Match.</param>
      <param name="index">Indicates the startindex of the Match.</param>
    </member>
    <member name="P:SyntaxHighlighter.Match.MatchType">
      <summary>Gets the <see cref="T:SyntaxHighlighter.MatchType">MatchType
               </see> of the Match.</summary>
      <value>Represents the <see cref="T:SyntaxHighlighter.MatchType">
             MatchType</see> of the Match.</value>
      <returns>A <see cref="T:SyntaxHighlighter.MatchType">MatchType</see>
               enumeration value.</returns>
      <seealso cref="T:SyntaxHighlighter.MatchType"/>
    </member>
    <member name="P:SyntaxHighlighter.Match.Index">
      <summary>Gets the startindex of the Match within the
               <see cref="T:SyntaxHighlighter.Sourcecode"/> object.</summary>
      <value>Represents the startindex of the Match within the
             <see cref="T:SyntaxHighlighter.Sourcecode"/> object.</value>
      <returns>The startindex of the Match within the
               <see cref="T:SyntaxHighlighter.Sourcecode"/> object.</returns>
      <seealso cref="T:SyntaxHighlighter.Sourcecode"/>
    </member>
    <member name="M:SyntaxHighlighter.Match.ToString">
      <summary>Returns a System.String that represents the current Match.
      </summary>
      <returns>A System.String that represents the current Match object.
      </returns>
    </member>
    <member name="M:SyntaxHighlighter.Match.Equals(System.Object)">
      <summary>Determines whether this instance of SyntaxHighlighter.Match and
               a specified object are equal.</summary>
      <remarks>Equality between the two matches is based on equality between the
               <see cref="P:SyntaxHighlighter.Match.Index"/> and
               <see cref="P:SyntaxHighlighter.Match.Value"/> properties.
      </remarks>
      <param name="obj">The object to compare the current Match with.</param>
      <returns><c>True</c> if <see cref="P:SyntaxHighlighter.Match.Index"/> and
               <see cref="P:SyntaxHighlighter.Match.Value"/> of the current
               Match and <paramref name="obj"/> are equal.
               Otherwise <c>False</c>.</returns>
    </member>
    <member name="T:SyntaxHighlighter.Match">
      <summary>Represents a match in Visual Basic sourcecode.</summary>
      <remarks>Examples of matches are comment, stringliteral and keyword
               matches.</remarks>
      <seealso cref="T:SyntaxHighlighter.MatchType"/>
      <seealso cref="T:SyntaxHighlighter.Sourcecode"/>
    </member>
    <member name="F:SyntaxHighlighter.MatchType.Comment">
      <summary>Used for comment matches.</summary>
    </member>
    <member name="F:SyntaxHighlighter.MatchType.Stringliteral">
      <summary>Used for stringliteral matches.</summary>
    </member>
    <member name="F:SyntaxHighlighter.MatchType.Keyword">
      <summary>Used for keyword matches.</summary>
    </member>
    <member name="T:SyntaxHighlighter.MatchType">
      <summary>Specifies the type of a <see cref="T:SyntaxHighlighter.Match"/>.
      </summary>
    </member>
  </members>
</doc>
Bemerkt hoe het hier niet gaat over een hierarchische representatie van onze code, maar een gewone sequentiële opsomming is van de verschillende types en members in <member> nodes.

Het name attribuut bevat een ID string die uniek is voor elk type of member.
Het eerste karakter (voor de dubbelpunt) geeft aan om wat voor member het gaat :

- N voor namespace
- T voor datatype (Class, Structure, Module, Interface, Enum of Delegate)
- M voor een method (Sub, Function, Declare of Operator)
- E voor event
- P voor property
- F voor field

De rest van de ID string bestaat uit de fully qualified identifier en optioneel een parameterlijst.

Deze output XML documentatie kan nu door tools gebruikt worden om van een namespace, type of member de beschrijvende informatie op te vragen.

Dit artikel is gepubliceerd op maandag 15 oktober 2012 op vbvoorbeelden, bezoek de website voor een recente versie van dit artikel of andere artikels.