4. Dokumentation

Dokumentation

  • T

    Ich bin gerade dabei, mein Projekt zu dokumentieren und bin am rätseln, wie ich das am besten mache. Ich beschreibe mal, was ich auf die Schnelle über Dokumentation gefunden habe und hoffe, dass Ihr auch Eure Erfahrungen schildert. Meine Suche brachte bisher folgende Ergebnisse:

    Es gibt unterschiedliche Tools, die die Dokumentation im Quellcode unterstützen.

    1. CSC
    Visual Studio verwendet CSC für XML-Kommentare. Leider unerstützt C++/CLI nicht das automatische Einfügen von XML-Kommentaren und die Intellisense-Unterstützung (im Gegensatz zu C#). Es kann aber ein XDC-Dokument erzeugt werden, das mit Hilfe von weiteren Tools (z.B. Sandcastle siehe http://www.artiso.com/ProBlog/PermaLink,guid,6e587e91-3c25-4e3c-ba06-16fe6c3adaf1.aspx) zu einem fertigen HTML Dokument geformt werden kann, das dann auch die integrierte Hilfe verwenden kann.

    2. Doxygen (http://www.stack.nl/~dimitri/doxygen/index.html)
    Ein mächtiges Open-Source Dokumentationswerkzeug, das sogar C++ Vererbungsdiagramme erzeugen kann. Die Suche hat ergeben, dass Properties bis vor einem Jahr noch nicht unterstützt wurden. Vielleicht kann mir jemand den aktuellen Stand sagen. Ansonsten unterstützt Doxygen so ziemlich alle Ausgabeformate. Vielleicht kann ja jemand schildern, wie leicht - oder schwer Doxygen zu bedienen ist, wenn man z.B. eine HTML-API schreiben will.

    3. Javadoc
    Wird für Java verwendet. Ich habe aber bis jetzt nicht herausgefunden, ob sich das auch für C++/CLI und Visual Studio eignet.

    4. weitere komerzielle Tools, die für mich aber nicht in Frage kommen.

    0
  • J

    Mit Visual Assist X kannst Du Makros erstellen, die den "automatischen C#" Kommentaren entsprechen. Soomit kannst Du auch ganz komfortabel in C++/CLI die Dokumentation erstellen.

    0
  • T

    Ich verwende jetzt die integrierten XML-Kommentare von Visual Studio. Damit kann man mit dem <summary>-Tag die Klassen, Membervariablen und -funktionen und Felder kurz beschreiben. Es gibt noch viel mehr Tags, die man verwenden kann. Eine Beschreibung findet man in der MSDN-Doku.

    Mit der Comiler-Option Ausgabedateien muss man bei "XML-Dokumentationsdateien generieren" Ja einstellen. Es werden dann alle XML-Kommenatare gebündelt in einer XML-Datei "Projet.xml" im debug oder release Verzeichnis dargestellt. Mit Hilfe von Sandcastle (Kommandozeilen-Tool) und dem Tool Sandcastle Help File Builder (GUI zu Sandcastle) kann man dann diese XML-Datei zusammen mit dem Assembly laden und zu einer CHM Hilfe-Datei kompilieren. Diese HilfeDatei sieht dann ähnlich aus wie die Hilfe der MSDN.

    Diese Lösung gefällt mir recht gut und scheint auch stabil zu funktionieren.

    0
  • G

    taraneas schrieb:

    ....Leider unerstützt C++/CLI nicht das automatische Einfügen von XML-Kommentaren und die Intellisense-Unterstützung (im Gegensatz zu C#). Es kann aber ein XDC-Dokument erzeugt werden,....

    Soweit auch mein Stand. Habe VS2005 Standard und die Intellisense-Unterstützung bei C++/CLI will nicht. Geht es nicht doch irgendwie? ... ein xdc-Dokument wird aber erzeugt....

    Habe jetzt gelesen unter
    http://msdn.microsoft.com/de-de/library/s0we08bk(VS.80).aspx
    dass auch normale Kommentare, z.B. "//Text" mit Intellisense angezeigt werden, aber bei mir funkt. das nicht. Kann das die Standard-Version von VS nicht?

    0
Anmelden zum Antworten