Wer seinen Quellcode kommentiert hat, und daraus nun z.B. eine Windows-Hilfe-Datei erstellen will, sollte zunächst in den jeweiligen Projekt-Eigenschaften unter "Erstellen" die Option "XML-Dokumentationsdatei" aktivieren, der vorgegebene Pfad kann beibehalten werden, er ist relativ zum Projektverzeichnis.
Die jeweiligen XML-Dateien werden bei jedem Build neu erstellt.
Um aus diesen Programmen nun einen normal lesbaren Text zu erstellen, benötigt man zusätzliche Tools.
NDoc (veraltet)
Für .NET1.1/Visual Studio .NET 2003 gab es NDoc, ein OpenSource-Projekt auf
http://ndoc.sourceforge.net/, dieses wird jedoch seit 2005 nicht mehr weiterentwickelt.
NDoc05
Das Nachfolgeprojekt von NDoc, NDoc05 befindet sich ebenfalls SourceForge unter
"http://sourceforge.net/projects/ndoc05/" und unterstützt auch .NET2.0/Visual Studio 2005.
Wenn man das Programm öffnet, kann man mit dem Punkt "From Visual Studio 2005 Solution" automatisch die Einstellungen und verwendeten Projekte einer Visual Studion 2005-Projektmappe übernehmen.
Dann sollte man noch einige Einstellungen bzgl. Titel, Namespace, ... vornehmen, und kann dann direkt die erste Hilfedatei erstellen.
Wer bei der Erstellung die Fehlermeldung
| Fehlermeldung: |
| Exception: NDoc.Core.DocumenterException |
erhält, sollte überprüfen, ob alle für die zu dokumentierende Projektmappe benötigten Assemblies (ausser den .NET-Assemblies) in den entsprechenden Verzeichnissen liegen.
Wer die Fehlermeldung
| Fehlermeldung: |
Exception: NDoc.Core.DocumenterException
at NDoc.Documenter.Msdn.MsdnDocumenter.Build(Project _project) in C:\Documents and Settings\Administrator\Desktop\NDoc2005\src\Documenter\Msdn\MsdnDocumenter.cs:line 565
at NDoc.Gui.BuildWorker.ThreadProc() in C:\Documents and Settings\Administrator\Desktop\NDoc2005\src\Gui\BuildWorker.cs:line 88 |
erhält (wichtig sind hier die Dateien MsdnDocumenter.cs und BuildWorker.cs), der wird nicht umher kommen, den Quellcode anzupassen. NDoc mag' es nicht, wenn referenzierte Assemblies nicht als lokale Kopie vorliegen (auch wenn dies in den Projekteinstellungen so eingestellt ist), und hat teilweise Probleme mit dem Zugriff auf einige, selbsterstellte HTML-Dateien.
Die Änderungen betreffen die Datei "MsdnHtmlUtilitiesV20.cs", Zeile 263, Methode InitializeNamespaces:
Im Abschnitt
 C#-Code: |
if (assembly == null)
{
throw new System.IO.FileNotFoundException(String.Concat("Unable to locate the referenced Assembly ", an.Name));
}
|
ist vor der throw-Zeile ein "continue" einzusetzen. Auswirkungen in der Hilfedatei habe ich noch nicht feststellen können.
Eine weitere Änderung ist evtl. in Zeile 330, in der Methode UpdateHtmlHrefs nötig.
Dort habe ich den Abschnitt
| C#-Code: |
System.IO.File.Replace(tempFile, fullPath, fullPath + ".bak");
System.IO.File.Delete(fullPath + ".bak");
|
durch
| C#-Code: |
System.IO.File.Copy(tempFile, fullPath, true); |
ersetzt, danach hat bei mir alles fehlerfrei funktioniert.
SandCastle
Ein anderes Programm ist SandCastle, zu finden unter "http://www.sandcastledocs.com".
SandCastle ist ein Kommandozeilen-Programm, welches jedoch auch eine Gui mitbringt, die nahezu identisch mit der von NDoc und NDoc05 ist, somit ist auch die Bedienung analog zu diesen Programmen.
Der einzige Unterschied liegt darin, dass die erstellten Hilfedateien ein wenig anders aussehen.
DoxyGen
Ein weiteres Programm ist "Doxygen", zu finden unter "http://www.doxygen.org/", Informationen gibt's auch unter "http://de.wikipedia.org/wiki/Doxygen". Leider habe ich mit diesem Programm noch nicht gearbeitet, scheint aber für C# auch nur bedingt geeignet zu sein. Wenn jemand Erfahrungen damit hat, kann er diesen Beitrag ja entsprechend erweitern ...
Die erstellte Hilfedatei
Wenn NDoc/NDoc oder Sandcastle ohne Fehlermeldung durchgelaufen sind, ist das Resultat eine Hilfe-Datei im CHM-Format. Wenn man diese Datei öffnet, und im Viewer auch links die Baumansicht angezeigt wird, in der Ansicht aber die Meldung "Die Seite kann nicht angezeigt werden" oder "Aktion abgebrochen" erhält, kann folgendes versuchen:
- Wenn sich die Datei auf einem Netzlaufwerk befindet, die Datei auf ein lokales Laufwerk kopieren und nochmals prüfen (nach Microsoft's Denken scheinen Netzlaufwerke "böse" CHM-Quellen zu sein)
- Weiterhin prüfen, ob alle Rechte vorliegen, um die Datei zu öffnen
- Eine andere CHM-Datei öffnen. Wenn's funktioniert, liegt's an der erstellten CHM-Datei, ansonsten am System
- Die Datei auf einen anderen Rechner kopieren und dort testen. Wenn's da funktioniert, liegt's mit hoher Wahrscheinlichkeit am anderen Rechner/System, ansonsten stimmt evtl. etwas mit der Datei nicht.
.
: