Wir verwenden doxygen , um API-(Referenz-)Dokumentation für unseren Code zu generieren. Wir haben eine kleine Java-API und eine große C++-API. Das übliche Tool der Wahl für Java-APIs ist Javadoc, aber doxygen kann beides, und wir haben uns entschieden, ein einziges Tool für beide zu verwenden.
Mit Javadoc können Sie eine Übersicht für jedes Paket hinzufügen, indem Sie dem Quellcode eine speziell benannte Datei hinzufügen. Javadoc zeigt dann diese Übersicht mit so viel Dokumentation, wie Sie möchten, zusammen mit der Dokumentation für die einzelnen Klassen. Paketübersichten sind nützlich, um zu erklären, wie Gruppen verwandter Klassen zusammen verwendet werden sollen, und können Diagramme, Beispiele und mehr enthalten. Da sie Teil des Javadoc-Builds sind, können sie mit einzelnen Klassen (oder Methoden oder anderen Membern) verknüpft werden.
Wie mache ich das Äquivalent in Doxygen, sowohl für Java-Pakete als auch für C++-Namespaces (die wir ähnlich wie Pakete verwenden )? Ich weiß, dass ich die Hauptseite bearbeiten kann, die als Überblick über die gesamte API fungiert, aber ich möchte die Dokumentation mehr verteilen. Ich möchte keine Übersichtsseite; Ich möchte eine Übersichtsseite pro logischer Codepartition, und ich möchte, dass sich diese Übersicht im selben Verzeichnis wie der Code befindet (wo sie mit größerer Wahrscheinlichkeit auf dem neuesten Stand gehalten wird).
Gibt es eine Möglichkeit, dies mit doxygen zu tun, oder muss ich meine eigenen Tools schreiben, um Dateien zur doxygen-Ausgabe hinzuzufügen?
Wir haben dies gelöst, indem wir Übersichtsdateien im Markdown-Format in den Quellbaum eingefügt und eine kleine Konfigurationsänderung vorgenommen haben.
In Doxyfile setzen wir GENERATE_TREEVIEW auf yes . Dadurch wird das Inhaltsverzeichnis der Seitenleiste aktiviert, das benötigt wird, wenn Sie möchten, dass diese Übersichtsdateien tatsächlich irgendwo angezeigt werden. (Normalerweise gibt doxygen nur Codeelemente aus – Klassen, Schnittstellen usw. Die Baumansicht gibt Ihnen einen Ort, an dem Sie andere Dinge ablegen können.) Stellen Sie während der Bearbeitung von Doxyfile sicher, dass MARKDOWN_SUPPORT auf yes gesetzt ist. (Ich denke, das ist die Vorgabe.)
Wir haben dann jedem Unterverzeichnis in unserem Quellbaum eine Markdown-Datei (Erweiterung .md) hinzugefügt. Doxygen unterstützt alle üblichen Markdown-Features . Wir haben jede Datei so benannt, dass sie ihrem enthaltenden Verzeichnis entspricht. Beispielsweise haben wir im Verzeichnis „server“ die Datei server.md genannt.
Die übliche Doxygen-Baumansicht hat Abschnitte für Namespaces, Klassen, Dateien und vielleicht andere Dinge. (Dies kann je nach Sprache variieren; unsere ist C++.) Unsere zusätzlichen Dateien werden in einem Abschnitt über diesen Abschnitten angezeigt, was sinnvoll ist -- "classes" bezieht sich nur auf die Klassen, und die Paketübersicht, die erklärt, wie sie zusammenarbeiten, befindet sich oben das. Wir haben keine schickere Organisation versucht, da wir auf dieser Ebene nur wenige Dateien benötigten.