Switch to the English version

Mit Eric Woodruffs Sandcastle Help File Builder ist es recht einfach, aus Kommentaren im Code eine schicke Dokumentation in Form einer Hilfe-Datei zu generieren. Leider unterstützt die Software keine Lokalisierung. Mit ein paar Tricks geht es doch!

---

Prinzip

Die XML-Kommentar-Elemente werden im Code gedoppelt und jedes Einzel mit einem Attribut versehen, dass die zugehörige Sprache erkennbar macht. Über das Prebuild-Event wird die vom Compiler erstellte XML-Datei über XPath nach diesen Sprachkennzeichen gefiltert. Die so gefilterte Datei wird dann dem weiteren Prozess zur Generierung der Hilfe-Datei zur Verfügung gestellt.

---

Vorbereitung / Installation

Den SHFB (Sandcastle Help File Builder) erhält man über GitHub: EWSoftware/SHFB. Hier nutzt man am besten den Installationsassistenten. Der sorgt auch dafür, dass Visual Studio mit den SHFB-Projekten klar kommt.

Das Filtern per XPath habe ich mit XMLStarlet Command Line XML Toolkit vorgenommen.

Visual Studio muss so eingestellt sein, dass eine XML-Dokumentationsdatei erzeugt wird. Dies geschieht über die Eigenschaftsseite des Projekts:

Code kommentieren

Die folgende Beschreibung gilt für ein Visual-Basic-Projekt. Für ein c#-Projekt müssen entsprechende Anpassungen gemacht werden. Die Beispiele entstammen meinem Projekt UrsLibrary.

Die Kommentierung des Codes erfolgt wie gewohnt. Jedoch muss jedes Element, dass in mehreren Sprachen dokumentiert werden soll, für jede Sprache einen gedoppelten Eintrag besitzen. Jeder Eintrag hat ein zusätzlich lang-Attribut mit dem betreffen Sprachenkürzel. Das folgende Beispiel mach dies deutlich:

   ''' <summary lang="en">
   '''    Initializes a new instance of the <see cref="System.Random"/> class, using the specified seed value.
   ''' </summary>
   ''' <summary lang="de">
   '''    Initialisiert eine neue Instanz der <see cref="UrsRandom"/>-Klasse unter Verwendung des angegebenen Startwerts.
   ''' </summary>
   ''' <param  name="Seed" lang="en">
   '''    A number used to calculate a starting value for the pseudo-random number sequence.
   '''    If a negative number is specified, the absolute value of the number is used.
   ''' </param>
   ''' <param name="Seed" lang="de">
   '''    Eine Zahl, mit der ein Startwert für Folgen von Pseudozufallszahlen berechnet wird.
   '''    Wenn eine negative Zahl angegeben wird, wird der absolute Wert der Zahl verwendet.
   ''' </param>
Sub New(Seed As Integer)
   ...

Build-Ereignisse einstellen

Bei den Projekte, die in die Dokumentation aufgenommen werden sollen, werden die folgenden Post-Build-Ereignisse aufgenommen. Sie bewirken das erstellen der sprachspezifischen XML-Dateien.

"C:\Program Files (x86)\xmlstarlet\xml" ed -d "//*[@lang != 'de']" "$(TargetDir)$(TargetName).xml" >"$(TargetDir)$(TargetName)-DE.xml"
"C:\Program Files (x86)\xmlstarlet\xml" ed -d "//*[@lang != 'en']" "$(TargetDir)$(TargetName).xml" >"$(TargetDir)$(TargetName)-EN.xml"

Was passiert hier? Die vom Compiler generierte XML-Dokumentationsdatei UrsLibrary.xml im Ausgabe-Verzeichnis (…\bin\Release\) wird über des Programms xml (XMLStarlet, s.o.: Vorbereitung/Installation) in die Datei UrsLibrary-DE.xml kopiert. Dabei werden alle Einträge entfernt (Option ed -d), die ein lang-Attribut besitzen, dass nicht das angegebene Kürzel enthält (Option "//*[@lang != 'de']").

SHFB-Projekt erstellen

Bevor man das SHFB-Projekt erstellt, muss man die betroffenen Code-Projekte einmal erstellen, damit die sprachspezifischen XML-Dateien erstellt wurden.

 Das Ganze beginnt damit, dass man ein neues SFHB-Projekt der Solution hinzufügt. Das SHFBProjekt-Template findet man unter Projektmappe → hinzufügen → Neues Projekt…→ Installiert → Documentation. Praktischerweise gibt man dem Projektnamen gleich eine Sprachenkennung mit, also z.B.: "UrsLibraryDoc-DE".

Dem Solution-Ordner wird nun ein neuer Ordner mit der gewählten Bezeichnung und einem Standard-Inhalt hinzugefügt.

Auch der Projektmappen-Explorer erhält einen entsprechenden Eintrag.

Die Eigenschaften des Projekts passt man nun den Erfordernissen und fügt zusätzliche Inhalte in der gewählten Sprache hinzu. Hier hilft die dem SHFB beigefügte Hilfe-Datei weiter.

Es fehlen noch die Documentation Sources. Hier wird normalerweise die XML-Dokumentationsdatei UrsLibrary.xml angegeben. Diese enthält jedoch noch Einträge zu allen dokumentierten Sprachen. Man müsste UrsLibrary-DE.xml  auswählen können. SFHB lässt aber nicht zu, dass ein beliebiger Datenamen angegeben wird. Die Datei muss existieren! Deshalb ist es zunächst notwendig einmal zu Beginn eine Datei mit dem gewünschten Namen zu erzeugen. Die Datei kann beliebigen Inhalt haben, sie wird sowieso über das Prebuild-Kommando überschrieben.

Über Add Documentation Source wird nun die .DLL und die gerade erzeugte Datei ausgewählt.

Leider wird die Standard-XML-Datei ebenfalls in die Liste eingefügt. Diese muss man manuell löschen.

Zuletzt sollte man sicherstellen, dass die Abhängigkeiten zwischen den einzelnen Projekten korrekt eingestellt sind. Ansonsten kann es sein, dass der Build-Vorgang nicht alle Dateien aktualisiert, von denen das SFHB-Projekt abhängig ist.

Das war's. Wenn jetzt das SHFB-Projekt oder die gesamte Projektmappe erstellt wird, wird eine Hilfe-Datei erstellt, die nur die Komponenten mit lang-Attribut enthält, dessen Inhalt "de" ist.

Für die Hilfe-Dateien in anderen Sprachen wiederholt man diesen Vorgang oder kopiert das bestehende Projekt und ersetzt das Sprachenkürzel entsprechend.

Wer sich das ganze im Visual Studio anschauen möchte, lädt dich die VS-Solution von UrsLibrary herunter. Es sind z.Z. aber nur wenige Code-Kommentare mehrsprachig hinterlegt. Aktuell ist dies im Namespace UrsUtilities bei der Klasse UrsRandom der Fall.

IntelliSense

Das Verhalten von IntelliSense, welche der möglichen summary-Tags angezeigt werden, ist noch ein wenig unklar. Weder MSDN noch Google haben hier weitergeholfen. Folgende Regel scheint in (der deutschen Variante von) VS hinterlegt zu sein:

• Wird zur Kennzeichnung der Sprache das Attribut lang verwandt, wird der Text angezeigt, der die Attributausprägung "en" ist.
• Hat das Attribut eine andere Bezeichnung oder hat keines der lang-Attribute die Ausprägung "en", wird der zuerst angegebene Text verwandt.

Je nach Verwendungszweck ist also zu überlegen, wie die Sprachenkennzeichnung erfolgt und in welcher Reihenfolge die Hilfe-Texte angegeben werden.