Automatiskt dokumentera C# kod

I C# används XML-kommentarer för att skapa dokumentation för metoder, klasser, egenskaper och andra typer. Dessa XML-kommentarer skrivs ovanför den kod som de dokumenterar och kan innehålla information om parametrar, returvärden, undantag, exempel och annan som är relevant. Vi ska nu se hur vi kan generera XML-kommentarer automatiskt.

Installera extension i VS code

Vi behöver installera en extension i Visual Studio Code som heter C# XML Documentation Comments.

Konfigurera ditt projekt

Vi börjar med att kopiera vårt projekt “MyBank” och lägger det i rotkatalogen för kmom06.

Vi behöver göra ett tillägg i projektfilen som ser ut så här:

// i kmom06/MyBank/src/MyBank.csproj
...
  <PropertyGroup>
    ...
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

När vi satt GenerateDocumentationFile till true så kommer den att varna för alla publika attribut och egenskaper som vi missat att dokumentera. Det allra bästa är att lägga till dokumentation för dessa, men för att undvika varningar kan vi lägga till:

// i kmom06/MyBank/src/MyBank.csproj
...
  <PropertyGroup>
    ...
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>

Generera XML-kommentarer

Gå in i din fil och skriv /// (3 stycken slash) raden över det du vill dokumentera. Då genereras en kommentar. Kolla i dokumentationen för tillägget så visar det hur du ska göra.
Du får själv fylla i vad respektive metod, utför och vad den returnerar. Du får även fylla i vad attributet är till för. Vi slipper i alla fall skriva strukturen runt kommentaren genom att skriva ///.

Exempel attribut

Vi tittar på klassen Bank i MyBank och attributet BankName. Skriv ///.

// i kmom06/MyBank/src/Bank.cs
...
public class Bank
{
    ///
    public string BankName;

Då blir den genererade kommentaren:

// i kmom06/MyBank/src/Bank.cs
...
public class Bank
{
    /// <summary>
    /// The class Bank contains bank accounts. Bank accounts can be added and
    /// the number of bank account can be returned.
    /// Bank offers possibilities to print information about the bank and the
    /// bank accounts.
    /// </summary>
    /// <value></value>
    public string BankName;

När vi uppdaterat den, så ser den ut så här:

// i kmom06/MyBank/src/Bank.cs
...
public class Bank
{
    /// <summary>
    /// The name of the bank.
    /// </summary>
    public string BankName;

Vi väljer att inte ha med value då vi tycker att det blir samma som i summary för ett attribut.

Exempel metod

Vi titta på klassen Bank i MyBank och metoden GetNoOfAccounts(). Skriv ///.

// i kmom06/MyBank/src/Bank.cs
...
public class Bank
{
  ...
    ///
    public string GetNoOfAccounts()

Då blir den genererade kommentaren:

// i kmom06/MyBank/src/Bank.cs
...
public class Bank
{
  ...
    /// <summary>
    ///
    /// </summary>
    /// <returns></returns>
    public string GetNoOfAccounts()

När vi uppdaterat den, så ser den ut så här:

// i kmom06/MyBank/src/Bank.cs
...
public class Bank
{
  ...
    /// <summary>
    /// This method returns the number of accounts in the bank.
    /// </summary>
    /// <returns>The number of bank accounts as a string.</returns>
    public string GetNoOfAccounts()

Om metoden returnerar ett objekt av klasstypen BankAccount så kan kommentaren se ut så här:

    /// <returns>A <see cref="BankAccount"/> object with account information.</returns>

Den genererade kommentaren för en metod med parameter ser ut så här:

    /// <summary>
    ///
    /// </summary>
    /// <param name="newAccount"></param>

Ifylld ser den ut så här:

// i kmom06/MyBank/src/Bank.cs
...
public class Bank
{
  ...
    /// <summary>
    /// This method adds a new bank account to the bank.
    /// </summary>
    /// <param name="newAccount">The object of a BankAccount.</param>
    public void AddAccount(BankAccount newAccount)

Ibland blir det dubbla <summary> taggar när vi genererar en kommentar över klassen. Men det är i alla fall bättre än att skriva alla taggar själv.

Andra exempel

Om du vill titta på exempel på hur koden i MyBank kan dokumenteras, så laddar du ner den med task download-code -- kmom06/MyBank.

Automatgenerera XML-kommentarer för en klass

Vi jobbar igenom klassen Bank och automatgenererar XML-kommentarer till den.

Generera dokumentation

Installera DocFX

DocFX är ett verktyg för att generera dokumentation från källkoden. Det stöder flera programmeringsspråk, inklusive C#, och extraherar automatiskt XML-kommentarer för att skapa användbar och lättläst dokumentation. Med DocFX kan utvecklare skapa snygga och strukturerade dokumentationssidor som inkluderar API-referenser, kodexempel, och användarguider. Det är ett kraftfullt verktyg som hjälper till att göra dokumentationsprocessen mer effektiv och professionell.

Installera DocFX globalt så här:

dotnet tool install -g docfx // installation
dotnet tool list -g // kolla alla verktyg (tools) i dotnet
docfx --version // ger versionen av docfx

DocFX, initiera dokumentationen

DocFX är ett verktyg från Microsoft som används för att generera statisk dokumentation från C#-kod och Markdown-filer. Det är särskilt användbart för att skapa API-dokumentation direkt från XML-kommentarer i vår kod.

Nu ska vi initiera vår dokumentation och det gör vi så här (välj default så uppdaterar vi konfigurationsfilen sen):

// Stå i kmom06/MyBank
docfx init

Input till docfx kommandot

Om vi svarar med . på frågan ”.NET projects location (src):” för då får vi projektet vi står i, vilket är “MyBank”.

This utility will walk you through creating a docfx project.
It only covers the most common items, and tries to guess sensible defaults.

Name (mysite): MyBank
Generate .NET API documentation? [y/n] (y): y
.NET projects location (src): .
Markdown docs location (docs): docs
Enable site search? [y/n] (y): y
Enable PDF? [y/n] (y): y

About to overwrite existing file ...
Is this OK? [y/n] (y): y

Och y på resten av frågorna

Det är viktigt att det stämmer med path till våra klasser, dubbelkolla att din docfx.json ser ut så här i början. Dubbelkolla att src innehåller, ”../.”. Projektfilen MyBank.csproj ska ligga i samma katalog som docfx.json filen gör.

// I kmom06/MyBank/src/docfx.json
{
  "metadata": [
    {
      "src": [
        {
          "src": "../.",
          "files": [
            "**/*.csproj"
          ]
        }
      ],
      "dest": "api"
    ...
    "globalMetadata": {
      "_appName": "MyBank",
      "_appTitle": "MyBank",
      "_enableSearch": true,
      "pdf": true
    }
  }
}

Nu får du dokumentation genererad för alla projekt i din katalog. Vi får för “FileApp”, “Badbank”, “GoodBank” och resten av projekten i katalogen. Om vi bara vill ha för “MyBank” gör vi så här:

// I kmom06/MyBank/src/docfx.json
{
  "metadata": [
    {
      "src": [
        {
          "files": [
            "MyBank.csproj"
          ]
        }
      ],
      "dest": "api"
    ...
    "globalMetadata": {
      "_appName": "MyBank",
      "_appTitle": "MyBank",
      "_enableSearch": true,
      "pdf": true
    }
  }
}

Vi har endast kvar raden "files: ["MyBank.csproj"] om vi bara vill ha dokumentation för projektet “MyBank”.

DocFX, starta dokumentationen

Nu skapar vi och kör igång webbsidan med dokumentationen genom att köra kommandot nedan. Du hittar dokumentationen för dina klasser under “API”.

docfx docfx.json --serve // starta servern

Nu startar en http server på <http://localhost:8080> med dokumentationen du nyss genererade.

Så här ser det ut på startsidan:

Image description — Bild: docfx startsida för MyBank

Klasserna ligger under fliken “API” överst i navbaren. Klicka på den. Det ser då ut så här:

OBS Om du får problem och inte ser något på dokumentsidan som har med dina klasser att göra, prova att stänga ner servern, ta bort katalogerna (MyBank/_api och MyBank/_site), kör om metadata kommandot docfx metadata och starta servern igen.

Sammanfattning

Vi har lärt oss att dokumentera vår kod med automatgenererade kommentarer samt generera dokumentation om koden.