|
Dit artikel is gepubliceerd op zondag 31 juli 2011 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 2010 Broncode Namespace SyntaxHighlighter Public Enum MatchType Comment Stringliteral Keyword End Enum Public Class Match Private m_Index As Integer Private m_MatchType As MatchType Public Sub New( ByVal matchType As MatchType, ByVal index As Integer) m_MatchType = matchType m_Index = index End Sub Public ReadOnly Property MatchType() As MatchType Get MatchType = m_MatchType End Get End Property Public ReadOnly Property Index() As Integer Get Index = m_Index End Get End Property Public Overrides Function ToString() As String ToString = End Function 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 ClassEnd NamespaceDownload Visual Basic 2010 Broncode Download Visual C# Sourcecode
32.2.1. <summary> en <remark> TagsGebruik 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.  boven
32.2.2. <c>, <code> en <example> TagsGebruik 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 :
boven 32.2.3. <param> en <paramref> TagsDe <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.
<paramref> met name attribuut ( <paramref name="..."> ) wordt dan gebruik om elders naar deze parameter te verwijzen boven 32.2.4. <value> en <returns> TagsDe <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. boven 32.2.5. <see> en <seealso> TagsGebruik binnen beschrijvende tekst de 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.
<seealso> is indentiek met als verschil dat hierbij de link naar dit type of member hierbij ook in de "See Also" rubriek terecht komt. boven 32.2.6. <exception> TagGebruik de <exception> tag met cref attribuut ( <exception cref="..."> ) om aan te geven wanneer deze exceptie, waar het cref attribuut naar verwijst, te omschrijven.
Bijvoorbeeld :
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 zondag 31 juli 2011 op vbvoorbeelden, bezoek de website voor een recente versie van dit artikel of andere artikels.
| 
31. 
