Microsoft Sandcastle ermöglicht es einem Entwickler seinen (hoffentlich) gut kommentierten Code automatisch z.B. in eine chm-Hilfedatei oder als Hilfe-Website generieren zu lassen. Dabei werden die Kommentare des Codes extrahiert und in diese Datei geschrieben.

Das Tool “Sandcastle Help File Builder” bietet eine GUI mit der das Generieren vereinfacht wird.

Download Sandcastle

Download Sandcastle Help File Builder

Damit das automatische generieren auch klappt, muss innerhalb von Visual Studio in den Project Properties das Häkchen “XML documentation File” aktiviert werden:

Der Name des XML documentation file ist im Prinzip frei wählbar. Allerdings gibt es hier einen kleinen Haken. In dem Beispiel heißt diese Datei “ProgramComment.xml”. Sollte bei der anschließenden Generierung mit dem SHFB die XML-Datei nicht gefunden werden (z.B. weist der Fehler: Missing <summary> darauf hin), sollte das XML documentation File umbenannt werden in “comments.xml”. Eine weitere Möglichkeit wäre es, die config-Datei des SHFB-Presentation zu bearbeiten (z.B. für vs2005):

Der Code

<!-- Copy in comments -->
        <component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <index name="comments" value="/doc/members/member" key="@name" cache="100">
            <data base="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727" recurse="false"  files="*.xml" />
            <data files=".\comments.xml" />

muss geändert werden in

<!-- Copy in comments -->
        <component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <index name="comments" value="/doc/members/member" key="@name" cache="100">
            <data base="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727" recurse="false"  files="*.xml" />
            <data files=".\*.xml" />

Da ich ausschließlich in C# entwickle, stelle ich in der Kategorie “Help File – SyntaxFilters” nur CSharp ein.

Bei der Visibility benutze ich gerne folgende Einstellungen im SHFB: