C# XML-dokumentation

C# har strukturerad API-dokumentation med ///-kommentarer. Rider och andra IDE:er kan visa sammanfattningar och parametrar i kodkomplettering. Bygget kan även generera en XML-fil som andra dokumentationsverktyg använder.

Beskriv beteende, inte bara signaturen

using System;

public static class InventoryRules
{
    /// <summary>Kontrollerar om ett slotindex får användas.</summary>
    /// <param name="slot">Nollbaserat index som ska kontrolleras.</param>
    /// <param name="capacity">Antalet platser, måste vara icke-negativt.</param>
    /// <returns>True bara om indexet är inom kapaciteten.</returns>
    /// <exception cref="ArgumentOutOfRangeException">
    /// Kastas när capacity är negativ.
    /// </exception>
    public static bool IsValidSlot(int slot, int capacity)
    {
        ArgumentOutOfRangeException.ThrowIfNegative(capacity);
        return slot >= 0 && slot < capacity;
    }
}

Sammanfattningen beskriver syftet, parametrarna anger gränser och exception-texten stämmer med implementationen.

Vanliga XML-taggar

Tagg	Användning
<summary>	Kort syfte som visas i IDE
<param name="...">	Indatakontrakt för anroparen
<returns>	Förklaring av returvärdet
<exception cref="...">	Villkor för relevanta undantag
<remarks>	Viktiga extra begränsningar
<typeparam name="...">	Generiska typparametrar
<see cref="..." />	Referens till kodsymbol
<example>	Exempel för anroparen

Bygg och granska

Aktivera <GenerateDocumentationFile>true</GenerateDocumentationFile> i projektfilen om XML-filen ska genereras. Kontrollera varningar om saknade eller felaktiga referenser. XML-kommentarer upprätthåller inte kontraktet automatiskt; tester och implementation måste stämma. Granska dokumentationen när publika API:er ändras.

Övning: Dokumentera en sökmetod som returnerar -1 om inget hittas. Förklara -1, null-indata och vilka undantag implementationen verkligen kastar.

Referenser: Microsoft XML-dokumentation och Rider.