XML-Dokumentation bei NuGet anhängen

Es gibt in C# die Möglichkeit, den eigenen Programmcode so zu dokumentieren, dass andere Entwickler in ihrer IDE unterstützt werden können. Dieser Artikel zeigt euch wie eine Dokumentation erstellt und in NuGet eingebunden wird.

Vorbereitung

In einem vorherigen Artikel habe ich bereits beschrieben, wie Nuget-Projekte erstellt werden . Dieser bietet euch einen schnellen Einstieg, um loszulegen.

Dokumentation schreiben

Für die Dokumentation gibt es XML-Kommentare . Ein einfaches Beispiel kann so aussehen:

/// <summary>
///   This method calculates the length of the given string.
///   NULL or empty strings are returning 0 (zero).
/// </summary>
/// <param name="stringToCalculate">Given string to calculate its length.</param>
public int CalculateLength(string stringToCalculate) {
  if (string.IsNullOrEmpty(stringToCalculate)) {
    return 0;
  } else {
    return stringToCalculate.Length;
  }
}

Im Gegensatz zu „normalen“ Kommentaren werden diese mit 3-Slashes (///) eingeleitet. Der summary Tag legt die Methodenbeschreibung fest. Mit Hilfe von param können einzelnen Parametern Beschreibungen zugewiesen werden. Diese zeigt das Visual Studio an, wenn der Cursor innerhalb der Funktionsparameter und Intellisense aktiviert ist.

Dokumentation aktivieren

Damit diese Dokumentation als Datei erzeugt wird, muss ein Häkchen gesetzt werden. Dadurch wird beim Kompilieren automatisch die XML-Datei erstellt.

Im nachfolgenden Screenshot ist der Haken in Rider dargestellt. Im Visual Studio gibt es unter den Projekteigenschaften und dem Build-Tab eine Option, die ähnlich heißt. Diese Option kann für Debug und Release individuell eingestellt werden.

Wir kompilieren das Projekt und sehen, dass nun im Ordner neben der DLL auch eine XML-Datei abgelegt wurde. Wenn wir diese öffnen, sehen wir dort unsere Methodenbeschreibung.

Das XML-Dokument sieht in meinem Falle folgendermaßen aus:

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>ClassLibrary2</name>
  </assembly>
  <members>
    <member name="T:ClassLibrary2.MyClass">
      <summary>
        This class contains some example functions.
      </summary>
    </member>
    <member name="M:ClassLibrary2.MyClass.CalculateLength(System.String)">
      <summary>
        This method calculates the length of the given string.
        NULL or empty strings are returning 0 (zero).
      </summary>
      <param name="stringToCalculate">
        Given string to calculate its length.
      </param>
    </member>
  </members>
</doc>

Dokumentation in Nuget einbinden

Wenn wir nun ein Nuget-Paket erzeugen ist die Dokumentationsdatei noch nicht enthalten. Das ändern wir durch Änderung der Projekteinstellungen. Dazu öffnen wir die .csproj-Datei im Editor.

Es gibt nun zwei Möglichkeiten, die Dokumentation einzubinden.

GenerateDocumentationFile

Bei der ersten Variante ergänzen wir die csproj-Datei um das Element GenerateDocumentationFile. Dieses Element muss in der ersten PropertyGroup gesetzt werden. Eure Projektdatei sollte nun folgendermaßen aussehen:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>netcoreapp2.2</TargetFramework>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>
</Project>

DocumentationFile

In der zweiten Variante wird die Dokumentationsdatei explizit gesetzt. Hierzu wird mit Hilfe des DocumentationFile-Elements die XML-Datei referenziert.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netcoreapp2.2</TargetFramework>
    <GeneratePackageOnBuild>true</GeneratePackageOnBuild>
  </PropertyGroup>

  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
    <DocumentationFile>bin\Debug\ClassLibrary2.xml</DocumentationFile>
  </PropertyGroup>

  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
    <DocumentationFile>bin\Release\ClassLibrary2.xml</DocumentationFile>
  </PropertyGroup>

</Project>

Inhalt vom Paket prüfen

Schauen wir uns zur Sicherheit das erstellte Nugetpaket an. Das Paket ist eine ZIP-Datei mit einer „speziellen“ Endung. Ihr könnt es mit einem beliebigen Zip-Programm öffnen.

Wenn ihr nun in den Ordner lib/netcoreapp2.2/ navigiert, dann findet ihr dort die kompilierte DLL und Dokumentation. Damit ist sichergestellt, dass die Konfiguration korrekt ist und die Dokumentation zusammen mit der Bibliothek ausgeliefert wird.

Fazit

Wir haben uns angesehen, wie eine XML-Dokumentation im Quellcode geschrieben und anschließend exportiert werden kann. Mit dem Parameter GenerateDocumentationFile ist es auf einfache Art und Weise möglich, die Dokumentation im Paket einzubinden. Habt ihr bereits die Dokumentation zu euren Bibliotheken ergänzt?

Bildnachweis: Pixabay.com