Elektronik, Multimedia & Technik

rating
3 Bewertungen

Doxygen - Die deutsche FAQ & Troubleshooting

Doxygen ist eine Dokumentationssoftware von Dimitri van Heesch und steht unter der GNU General Public License. Die Software findet man hier zum Download. Als kleine Hilfestellung für alle deutschen Nutzer von Doxygen haben wir hier sowohl die FAQ als auch das Troubleshooting aus dem Englischen ins Deutsche übersetzt. Die orginal Dokumente findet ihr hier und hier.

Doxygen Infoflow

FAQ

  1. Wie bekomme ich die Informationen auf der Index-Seite in HTML?

    Du solltest das mainpage Kommando im Kommentar benutzen:zurück nach Oben

    /*! mainpage My Personal Index Page
     *
     * section intro_sec Introduction
     *
     * This is the introduction.
     *
     * section install_sec Installation
     *
     * subsection step1 Step 1: Opening the box
     *  
     * etc...
     */
    
  2. Hilfe, einige oder alle Members meiner Klasse / meiner Datei / meines Namensraums sind nicht dokumentiert?zurück nach Oben

    Prüfe folgendes:

    1. 1. Ist deine Klasse / deine Datei / dein Namensraum dokumentiert? Wenn nicht wird es nicht aus dem Source extrahiert, solange EXTRACT_ALL nicht auf YES im Konfig-File gesetzt ist.
    2. Sind die Members private? Wenn dem so ist, musst du EXTRACT_PRIVATE auf YES setzten, damit sie in der Dokumentation auftauchen.
    3. Hast du ein Funktions-Marco in deiner Klasse, welches nicht mit einem Semikolon endet (z.B. MY_MARCO())? Wenn dem so ist musst du dem doxygen Präprozessor mitteilen, dass es diesen entfernen muss.

      Das kannst du normalerweise mit folgenden Einstellungen im Konfig-File erreichen:

      ENABLE_PREPROCESSING   = YES
      MACRO_EXPANSION        = YES
      EXPAND_ONLY_PREDEF     = YES
      PREDEFINED             = MY_MACRO()=
            

      Am besten liest du das Preprocessing Kapitel der Anleitung.

  3. Wenn ich EXTRACT_ALL auf NO stelle, tauchen meine Funktionen nicht in der Dokumentation auf.zurück nach Oben

    Damit globale Funktionen, Variablen, Enums, typedefs und defines in der Dokumentation stehen, solltest du sie in der Datei Dokumentieren, in der sie verortet sind und dabei einen Kommtarblock mit file (oder @file) benutzten.

    Alternativ kannst du auch alle Members in einer Gruppe (oder einen Modul) mithilfe des ingroup Kommandos zusammenführen, und dann die Gruppe mit defgroup Kommentieren.

    Für Member-Funktionen oder Funktionen die Teil eines Namensraums sind gilt, du solltest entweder die Klasse oder den Namespace kommentieren.

  4. Wie kann ich doxygen dazu bringen Code-Fragmente zu ignorieren?zurück nach Oben

    Der neue und einfachste Weg ist eine Kommentarblock mit cond vor und mit endcond nach dem zu ignorierende Code-Fragment. Diese Kommandos sollten natürlich im gleiche File sein.

    Aber du kannst auch den Doxygen Präprozessor dafür benutzten: Wenn du

    #ifndef DOXYGEN_SHOULD_SKIP_THIS
    
     /* code that must be skipped by Doxygen */
    
    #endif /* DOXYGEN_SHOULD_SKIP_THIS */
    

    um den zu verstekenden Code-Block schreibst und:

      PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS
    

    in das Konfig-file. Dann werden alle Code-Blöcke übersprungen solange PREPROCESSING = YES. eingestellt ist.

  5. Wie kann ich das ändern was nach #include in der Klassendokumentation kommt?zurück nach Oben

    In den meisten Fällen kann man STRIP_FROM_INC_PATH benutzen um einen Benutzerdefinierten Teil aus dem Pfad zu entfernen.

    Da kannst deine Klasse auch so Dokumentieren:

    /*! class MyClassName include.h path/include.h
     *
     *  Docs for MyClassName
     */
    

    Um Doxygen dazu zu bringen

    #include

    in die Dokumentation von der Klasse MyClassName zu schreiben, ungeachtet des Namens des aktuellen Header-Files welches die Definitionen der Klasse MyClassName enthält.

    Falls du Doxygen dazu bringen möchtest das Include-File statt mit eckigen Klammern mit Tüttelchen inkludiert wird:

    /*! class MyClassName myhdr.h "path/myhdr.h"
     *
     *  Docs for MyClassName
     */
    

  6. Wie kann ich Tag-Files in Kombination mit Compressed-HTML benutzten?zurück nach Oben

    Falls du von einem Compressed-HTML file a.chm ein anderes Compressed-HTML b.chm File referenzieren möchtest, so muss der Link in a.chm folgendes Format haben:

    
    

    Leider funktionier das nur falls beide Compressed-HTML files im gleichen Ordner liegen.

    Daraus resultierend musst du alle index.chm mit eindeutigen Namen versehen und in ein Ordner legen

    Wenn du z.B ein Projekt a hast, welches Projekt b referenziert und das Tag-File b.tag benutzt, dann kann du index.chm des Projektes a in a.chm und die index.chm des Projektes b in b.chm umbenennen. Im Konfigurationsfile des Projektes a schreibst du dann:

    TAGFILES = b.tag=b.chm::
    

    Oder du kannst die installdox benutzten um die Links zu setzten:

    installdox -lb.tag@b.chm::
    

  7. Ich mag den QuickIndex nicht, welcher über jeder HTML-Seite ist, was soll ich tun?zurück nach Oben

    Du kannst den Index ausschalten in dem du DISABLE_INDEX aud YES setzt. Dann kannst du deinen eigenen Header und Footer schreiben.

  8. Der Overall-HTML sieht anders aus, obwohl ich nur meinen eigenen HTML-Header anzeigen möchte.zurück nach Oben

    Möglicherweise hasst du das Stylesheet vergessen doxygen.css welches von doxygen generiert wird. Du kannst es so in deinen HEAD der HTML-Seite hinzufühgen:

    
    

  9. Warum benutzt Doxygen Qt?zurück nach Oben

    Der gewichtigste Grund ist, mit Hilfe von QFile, QFileInfo, QDir, QDate, QTime and QIODevice Klassen eine Abstraktionsebene für Plattformen zu erhalten. Ein weiterer Grund sind die schönen und Bugfeien Utility-Klassen wie z.B. QList, QDict, QString, QArray, QTextStream, QRegExp, QXML etc.

    Das GUI-Frontend doxywizard benutzt Qt für... nun ja ... für die GUI!

  10. Wie kann ich alle Test-Order aus meinem Ordnerbaum entfernen?zurück nach Oben

    Benutzt einfach ein Exlclude-Pattern in der Konfiguration wie z.B.: file:

    EXCLUDE_PATTERNS = */test/*
    

  11. Doxygen generiert einen Link zur Klasse "MyClass" irgendwo in Fließtext. Wie unterbinde ich das?zurück nach Oben

    Füge ein % vor den Klassennamen. Z.B: "%MyClass". Doxygen wird das % entfernen und den Klassennamen unverlinkt stehen lassen.

  12. Meine Lieblings-Programmiersprache ist X. Kann ich trotzdem Doxygen benutzten?zurück nach Oben

    Nein, nicht einfach so; Doxygen muss die Struktur dessen verstehen was er ließt. Wenn du nicht viel Zeit damit verschwenden willst gibt es dort einige Optionen:

    • Wenn die Grammatik von X nahe bei C order C++ liegt, ist es nicht schwer die src/scanner.l anzupassen damit auch X unterstützt wird. Dies ist schon für alle anderen Sprachen die von Doxygen unterstützt werden geschehen. (z.B. Java, IDL, C#, PHP).
    • Wenn die Grammatik von X anders beschaffen ist, kannst du einen Input-Filter schreiben, der X in etwas ähnliches wie C/C++ übersetzt damit doxygen es verstehen kann (Dieser Ansatz wird bei VB, Object Pascal und Javascript benutzt, siehe http://www.stack.nl/~dimitri/doxygen/download.html#helpers).
    • Wenn die Grammatik völlig anders ist könnte jemand einen Parser für X und ein Backend schreiben. Diese müssen dann einen gleichen Syntax-Baum erstellen, so wie src/scanneer.l es tut. (Und natürlich auch wie src/tagreader.cpp wenn die Tag-Files gelesen werden).

  13. Hilfe, ich bekomme die cryptische Fehlermeldung: "input buffer overflow, can't enlarge buffer because scanner uses REJECT"zurück nach Oben

    Dies Meldung tritt auf, falls doxygens Lexikalischer Scanner eine Regel hat, welche mehr als 256k (Inpup-Character) hat, in einem Zuge. so etwas habe ich gesehen bei sehr großen Dateien (>256k Zeilen), wo der build-in Präprozessor diese in eine leere neue Datei konvertiert hat (mit >256K neuen Zeilen) Ein anderer Fall wo die passieren kann ist, falls du Zeilen im Code hast, die mehr als 265k Buchstaben haben.

    Falls so etwas auftritt und ich es fixen soll, bitte sende mir das Code-Fragment welches zum Fehler führte. Als Workaround kannst du einfach Zeilenumbrüche einfügen, oder die Datei in kleinere aufteilen, oder es einfach mit EXCLUDE exkludieren.

  14. Wenn ich make im LeTeX Pfad ausführe erhalte ich: "TeX capacity exceeded". Was jetzt?zurück nach Oben

    Du kannst die texmf.cfg editieren um die Default-Werte einiger Buffer zu erhöhe, danach musst du "texconfig init" ausführen.

  15. Warum sind die Abhängigkeiten via STL-Klassen nicht im Graphen enthalten?zurück nach Oben

    Doxygen ignoriert die STL Klassen, solange die Option BUILTIN_STL_SUPPORT nicht angestellt ist.

  16. Ich habe Probleme die "search engine" mit PHP5 und/oder Windows zusammenarbeiten zu lassen.zurück nach Oben

    Bitte ließ dies für Tipps und Hinweise.

  17. Kann ich Doxygen von der Kommandozeile aus konfigurieren?zurück nach Oben

    Nicht über die Kommandozeile, aber doxygen kann von stdin lesen, also kannst du Dinge Pipen "|". Hier ist ein Beispiel, wie man Optionen der Konfiguration über die Kommandozeile überschreiben kann (Unix angenommen):

    ( cat Doxyfile ; echo "PROJECT_NUMBER=1.0" ) | doxygen -
    

    Falls mehrere Option mit dem selben Namen angegeben werden, wird doxygen die letzte nehmen. Um eine Option hinzuzufügen kannst du den += Operator benutzen.

  18. Woher kommt der Name "Doxygen"?zurück nach Oben

    Doxygen kommt aus dem Spiel mit den Wörtern "Dokumentation" und "Generator".

    documentation -> docs -> dox
    generator -> gen
    

    Zu der Zeit als ich mich viel mit lex und yacc beschäftig habe, fingen eine Menge Dinge mit "yy" an, also ist das "y" mit reingerutscht um es besser aussprechen zu können. (Die richtige Aussprache ist Docs-i-gen).

  19. Was war der Anlass um Doxygen zu entwickeln?zurück nach Oben

    Damals habe ich ein GUI-Widget mit det Qt lib erstellt, ( (Übrigend immer noch verfügbar unter http://qdbttabular.sourceforge.net/ betreut von Sven Meyer). Qt hat eine schöne generierte Dokumentation (welche von einem internen Tool generiert wird, welches sie nicht veröffentlichen wollten) und ich schrieb mir ähnliche Dokumentationen per Hand. Die Verwaltung dieser Dokumente war ein Alptraum, und ich wollte ein ähnliches Tool. Also schaute ich mit Doc++ an, aber das war für mich nicht gut genug (Es unterstütze keine "signals" und "slots" und ich hatte nicht das Qt Look-and-Feel, welches ich gewohnt war), also begann ich mein eigenes Tool zu schreiben...


Fehlerbehandlung

zurück nach Oben

Bekannte Probleme:

  • Falls du Probleme hast doxygen vom Quelltext zu kompilieren lies bitte zuerst die folgenden Hinweise bevor du dich an den Support wendest.

  • Doxygen ist kein ‘echter’ Compiler, sondern lediglich ein lexikalischer Scanner. Dies bedeutet, dass doxygen keine Fehler in deinem Quellcode identifizieren kann und wird.

  • Da es nahezu unmöglich ist alle Testfälle durchzuspielen ist es gut möglich, dass ein valider C/C++ Quellcode nicht korrekt behandelt wird. Falls du solch einen Fehler entdeckst, bitten wir dich uns dies mitzuteilen. So können wir Doxygen weiter verbessern. Versuche dabei bitte die Stelle im Quellcode möglichst genau zu lokalisieren, damit der Arbeitsaufwand unsererseits möglichst gering ist.

  • Doxygen kann nicht korrekt arbeiten, falls es bei der Benennung der ‚classes‘, ‚structs‘ oder ‚unions‘ zu gleichen Namen gekommen ist. Doxygen dabei in der Regel nicht abstürzen, allerdings wird es alle Klassen, abgesehen von der ersten, ignorieren.

  • Einige Kommandos funktionieren nicht als Argumente von anderen Kommoandos: Beispielsweise können innerhalb eines HTML Links (z.B. ...) keine anderen Kommandos (auch keine HTML Elemente) verwendet werden. Eine wichtige Ausnahme stellen hier allerdings die Aufteilungs-Kommandos dar.

  • Redundante Klammern können doxygen verwirren. Hier einige Beispiele:

    void f (int);

    wird sauber als Funktion deklariert, aber

    const int (a);

    wird auch als Deklaration einer Funktion behandelt mit dem Namen ‚int‘, da ausschließlich die Syntax analysiert wird, nicht die Semantik. Falls eine redundante Klammer erkannt wird, wie hier

    int * (a[20]);

    wird doxygen die Klammern entfernen und das Ergebnis wird korrekt interpretiert.

  • Nicht alle Namen werden in den Code-Fragmenten mit Links versehen (beispielsweise wenn SOURCE_BROWSER = YES benutzt wird) und überladene Funktionen können evtl. auf die falschen Funktionen verweisen. Dies gilt ebenfalls für die Referenzenliste, welche für jede Funktion generiert wird. Zum Teil passiert dies, weil der Parser nicht clever genug ist. Wir werden dieses Verhalten von doxygen natürlich versuchen weiter zu verbessern. Aber selbst weitere Verbesserungen werden dieses Problem nicht endgültig lösen können, da es immer wieder ein Defizit an Informationen beim Parsen gibt.

  • Es ist nicht möglich mittels relates oder relatesalso Kommandos in eine non-member Funktion f die Klasse A einzufügen, wenn die Klasse A bereits ein Mitglied mit dem Namen f und die gleichen Argumenten enthält.

  • Zurzeit werden Member Spezifikationen nicht voll unterstützt. Nur wenn eine spezielle Template Klasse eingesetzt wird funktioniert doxygen korrekt.

  • Nicht alle Kommandos werden korrekt zu RTF übersetzt.

  • Version 1.8.6 (evtl. auch die älteren Versionen) generieren keine einwandfreien Map Files, was dafür sorgt, dass die Graphen nicht leider klickbar sind.

  • Für PHP: Doxygen arbeitet nur einwandfrei, wenn alle Statements in Funktionen/Methoden gewrapt werden, andernfalls gibt es Probleme beim Parsen des Quellcodes.

Wie könnt ihr helfen?zurück nach Oben

Die Weiterentwicklung von doxygen lebt von eurem Feedback.

Falls ihr doxygen ausporbiert, lasst uns bitte wissen was du von der Software hältst (welche Features vermisst du?). Selbst wenn ihr euch dazu entscheidet doxygen nicht einzusetzen teilt mir bitte mit warum ihr so entschieden habt.

Wie kann ich einen Bug melden?zurück nach Oben

Fehler werden über GNOME's bugzilla dokumentiert. Bevor ihr einen neuen Fehler einreich-t vergewissert euch bitte mittels der Suche, ob der gleiche Fehler nicht schon eingereicht wurde. Falls ihr euch sicher seid, dass ihreinen nicht dokumentierten Fehler gefunden habt teilt diesen bitte hier mit.

Falls ihr euch nicht sicher seid, ob es sich um einen Fehler handelt fragt bitte in der Users Mailing List nach (Eine Beschreibung ist hier natürlich erforderlich).

Falls ihr nur eine vage Beschreibung des Fehlers abgebt, ist dies für uns natürlich nicht besonders hilfreich, denn es wird uns im Zweifelsfall sehr viel Zeit kosten zu verstehen was ihr eigentlich meinst. Im ‚Worst Case‘werden wir euren Fehlerbericht komplett ignorieren müssen, also versucht bitte dem fehlerbericht immerfolgende Informationen anzuhängen.

  • Eure aktuelle doxygen Version (Z.B. 1.5.3, falls du dir nicht sicher bist benutze einfach doxygen –version)

  • Name und Versionsnummer eures Betriebssystems (Zum Beispiel SuSE Linux 6.4)

  • Bitte sendet uns ebenfalls eure Konfigurationsdatei mit, aber bitte verwendet doxygen mit dem –s flag um eine kleine Datei zu erhalten (ihr könnt doxygen -s -u [configName] benutzen um aus einer existierenden Datei die Kommentare zu entfernen.

  • Der leichteste (und oft der einzige) Weg für uns einen Fehler zu beheben ist es, wenn ihr uns ein Beispiel mitschickt, welches den Fehler auslöst. So können wir das Problem am ehesten reproduzieren. Bitte stellt sicher, dass es sich um validen (also Code der sich ohne Fehler kompilieren läßt) Quellcode handelt und das der Ausschnitt auch wirklich das Problem beinhaltet (es passiert sehr oft, dass der Auszug überhaupt nicht das Problem wiedergibt). Falls ihr mehr als ein Dokument schickt komprimiert (zip or tar) diese bitte vorher zu einem Dokument. Das macht das Handling für uns wesentlich einfacher. Wir weisen euch hiermit darauf hin, dass ihr erst dann Dokumente schicken solltet nachdem ihr die Fehlerbeschreibung eingreciht habt. Ansonsten können wir die Dokumente nicht zuordnen.

Ihr könnt gerne (bitte fühlt euch dazu angespront) direkt eine Lösung für den Fehler mitliefern. Falls ihr dies macht, verwendet bitte in der Betreffzeile des Problemreports „PATCH“ als Schlüsselwort.

Falls ihr Lösungsvorschläge für existierende Probleme habt diskutiert diese doch bitte in der developers mailing list (Subscription erfoderlich). Patches können ebenfalls direkt an dimitri@stack.nl geschickt werden, falls ihr sie nicht über den Bug Tracker oder die Mailing Liste einreichen möchtet.

Für Patches benutzt bitte "diff -uN" oder fügt die Dateien hinzu die ihr geändert habt. Falls ihr mehr als eine Datei verschicken möchtet, bitte ich euch, diese vorher via zip oder tar zu einem Dokument zu komprimieren. Dies macht das Handling für uns einfacher, da wir so lediglich ein Dokument downloaden und speichern müssen.

zurück nach Oben
von Andrea Schulte
Gestellte Fragen: 1

Fragen zum Beitrag: “Doxygen - Die deutsche FAQ & Troubleshooting”

 
Frage 1
 
Gast - geschrieben am 09.01.2011 um 18:48

Umstellung Sprache

Wie kann ich oxygen auf Deutsch stellen?

Antworten 0 Es gibt noch keine Antworten auf diese Frage..

Kommentare

Bisherige Kommentare: 0