Inledning
I det här dokumentet vill jag beskriva hur man installerar, skriver och sedan konverterar kodkommentarer i Visual Studio 2005 och Visual Basic.NET.
Installera
Följande program behövs:
- Visual Studio 2005
- NDoc 1.3.1 (http://ndoc.sourceforge.net) Behövs bara om man skall konvertera kodkommentarerna som en hjälpfil.
Kommentarer till installationen av NDoc
För att få NDoc att fungerar för Visual Studio 2005 så måste man själv redigera i filen NDocGui.exe.config som finns i C:\Program Files\NDoc 1.3\bin\net\1.1, om man installerar programmet med standardvalen.
Raden <supportedRuntime version="v2.0.50727" /> skall läggas till. (Detta gäller för den officiella versionen av Visual Studio 2005.)
Att skriva dokumentationskommentarerna
Att skriva dokumentationskommentarer innebär helt enkelt att man beskriver Fält, Egenskaper, Klasser och Metoder på ett standardiserat sätt. Man ger dessa enheter helt enkelt ett huvud som är formaterat på ett rätt sätt.
Det innebär alltså att man beskriver innan enhetsdefinitionen. I Visual Basic gör man på följande sätt:
- Gå till raden ovanför det som skall dokumenteras.
- Skriv tre apostrofer (') efter varandra.
En grundmall kommer automatiskt att införas.
TIPS! Om du skall dokumentera en metod så skriv klart metodens signatur, inklusive returvärde och parametrar, innan du börjar dokumentera. Det är nämligen så att den mall som skapas tar hänsyn till signaturen och fyller på med information om parametrarna och returvärdet automatiskt.
Här kommer ett exempel på dokumentering för en metod:
''' <summary>
''' Gets the persons PersonNumber, if found, by searching <c>firstName</c>
''' and <c>lastName</c>.
''' <list type="bullet">
''' <item>Number A</item>
''' <item>Number B</item>
''' <item>Number C</item>
''' </list>
''' <list type="table">
''' <listheader>Greek characters</listheader>
''' <item><term>Alpha</term><description>The first letter</description></item>
''' <item><term>Beta</term><description>The second
''' letter</description></item>
''' <item><term>Gamma</term><description>The third
''' letter</description></item>
''' </list>
''' </summary>
''' <param name="firstName">Should be max 30 characters</param>
''' <param name="lastName">Should be max 40 characters</param>
''' <returns>The PersonNumber of the Person.</returns>
''' <remarks>This function is primary used when the user don't know
''' the PersonNumber of a Customer.
''' <example>
''' This example shows how how a customer with <c>firstName</c> Kalle
''' and <c>lastName</c> Eriksson is searched for.
''' <code>
''' Dim _person As New Person()
''' Dim _personNumber As Integer = _person("Kalle", "Eriksson")
''' </code>
''' </example>
''' </remarks>
''' <exception cref="System.ArgumentException">If firstName or
''' lastName is to long</exception>
Public Function GetPersonNumber(ByVal firstName As String, _
ByVal lastName As String) As Integer
End Function
Som ni marker har jag lekt med ett antal olika dokumenteringselement för att visa vad som går att göra. I verkligheten använder man vanligtvis inte alla dessa.
Här finns en beskrivning över alla standardelement som man kan använda sig av: http://msdn2.microsoft.com/en-us/library/ms172653(VS.80).aspx.
Att konvertera till dokumentation
Detta sker i två steg:
- När man kompilerar programmet kommer alla dokumentationskommentarer att extraheras och läggas i en xml-fil, i samma katalog som det kompilerade programmet.
Den här funktionen kan stängas av. För att den skall fungera måste kryssrutan Generate XML documentation file vara ifylld. Denna kan man finna i egenskaperna för projektet, under fliken Compile. - Använda sig av NDoc för att läsa Xml-filen (och också den kompilerade koden) för att skapa en hjälpfil.
Använda NDoc
NDoc finns i två versioner, en för kommandoraden och en med ett användargränssnitt. Jag visar endast den med användargränssnitt här.
Starta NDoc. Jag använder mig av den versionen som finns i undermenyn 1.1. (Det är den som vi tidigare har redigerat konfigurationsfilen för.)
Jag kommer inte här att beskriva alla de inställningar som man kan göra. Den enda inställningen som man måste göra, om man vill kodkommentera kod som sedan kommer att användas av Visual Basic är ShowVisualBasic. Den inställningen gör att definitionerna av fälten, egenskaperna, klasserna och metoderna kommer att visas både som C# och Visual Basic.
Det man behöver göra är att peka ut vart den kompilerade kodfilen. Det gör man genom att klicka på knappen Add och sedan ange en länk till den kompilerade koden i fältet Assembly.
NDoc hittar själv xml-filen och fyller i den i fältet SlashDoc.
Nu är det bara att klicka på ikonen Build Documentation på verktygsfältet och hjälpfilen kommer att skapas.
För att titta på hjälpfilen så kan du klicka på ikonen View Documentation som finns i samma verktygsfält.
Och här har vi resultatet av den koddokumentation som jag gjorde ovan.
