Objective-C-Dokumentationsgeneratoren: HeaderDoc vs. Doxygen vs. AppleDoc

Ich muss eine Lösung zur Dokumentationsgenerierung für meinen Arbeitsplatz implementieren und habe sie auf die drei im Titel genannten eingegrenzt. Ich konnte nur sehr wenige Informationen über formalisierte Vergleiche zwischen diesen Lösungen finden, und ich hoffe, dass diejenigen von Ihnen, die Erfahrung in einem oder mehreren der oben genannten Bereiche haben, Folgendes abwägen können:

Folgendes konnte ich aus meinem ersten Durchgang entnehmen:

HeaderDoc Vorteile: Im Einklang mit Apples bestehende Dokumente, die Kompatibilität mit Apple docsets machen
HeaderDoc Nachteile: Schwierige Verhalten zu ändern, wird Projekt nicht aktiv bearbeitet, von der sie viele haben weggeschaltet (was bedeutet , es muss etwas mangelhaft sein, obwohl ich es nicht quantifizieren kann ).

Doxygen Vorteile: Aktive Unterstützung Community b / c der breiten Verwendung Basis, sehr anpassbar, die meisten Ausgabetypen (wie Latex usw.)
Doxygen Nachteile: Arbeit nehmen , um es mit Äpfeln docs aussehen / behave konsistent zu machen, die Kompatibilität mit Apple docsets ist nicht so einfach

AppleDoc-Vorteile: Entspricht den vorhandenen
Dokumenten von Apple, der Kompatibilität mit der Erstellung von Apple-Dokumenten, AppleDoc-Nachteile: Problem mit der Dokumentation von Typedefs, Aufzählungen und Funktionen, die aktiv entwickelt werden

Klingt das genau? Unsere gewünschte Lösung hat:

• Konsistentes Erscheinungsbild mit Referenz der Apfel-Ziel-C-Klasse
• Möglichkeit zum Klicken mit der Option, um die Dokumentationsreferenz aus Xcode heraus aufzurufen und dann mit dem Dokument zu verknüpfen (genau wie bei den Apple-Klassen).
• Intelligente Handhabung von Kategorien, Erweiterungen und dergleichen (sogar benutzerdefinierte Kategorien von Apple-Klassen)
• Möglichkeit, eigene Referenzseiten zu erstellen (wie diese Seite: Laden…, die Bilder enthalten und nahtlos aus generierten Klassenreferenzen verknüpft werden können, z. B. wie die UIViewController-Klassenreferenz von Apple auf die verknüpfte Seite verweist.
• Einfach auszuführende Befehlszeilenbefehle, die in Build-Skripte integriert werden können
• Anmutiger Umgang mit sehr großen Codebasen

Ist eine der oben genannten Lösungen auf der Grundlage aller oben genannten Informationen eindeutig besser als die anderen? Vorschläge oder Informationen zum Hinzufügen wären sehr dankbar.

Lassen Sie mich als Schöpfer und Hauptentwickler von doxygen auch meine Perspektive angeben
(offensichtlich auch voreingenommen ;-)

Wenn Sie nach einer 100% originalgetreuen Nachbildung des Apple-eigenen Dokumentationsstils suchen, ist AppleDoc in dieser Hinsicht die bessere Wahl. Mit Doxygen fällt es Ihnen schwer, genau das gleiche Aussehen zu erhalten, daher würde ich nicht empfehlen, es zu versuchen.

In Bezug auf Xcode-Docsets; Apple bietet Anweisungen zum Einrichten mit Sauerstoff (geschrieben in der Zeit, als Xcode 3 veröffentlicht wurde). Für Xcode 4 gibt es auch eine nette Anleitung, wie man Sauerstoff integriert.

Ab Version 1.8.0 unterstützt doxygen das Markdown-Markup sowie eine große Anzahl zusätzlicher Markup- Befehle.

Mit doxygen können Sie Dokumentation sowohl auf der Hauptseite (@mainpage) als auch auf Unterseiten (mit @subpage oder @page) einfügen. Innerhalb einer Seite können Sie Abschnitte und Unterabschnitte erstellen. Tatsächlich wurde das Benutzerhandbuch von doxygen vollständig mit doxygen geschrieben. Außerdem können Sie Klassen oder Funktionen zusammen gruppieren (mit @defgroup und @ingroup) und innerhalb einer Klasse benutzerdefinierte Abschnitte erstellen (mit @name).

Doxygen verwendet eine Konfigurationsdatei als Eingabe. Sie können eine Vorlage mit Standardwerten mithilfe doxygen -geines grafischen Editors erstellen oder verwenden, um eine Vorlage zu erstellen und zu bearbeiten. Sie können Optionen auch über ein Skript mithilfe von doxygen weiterleiten doxygen -(siehe Frage 17 der FAQ für ein Beispiel).

Doxygen ist nicht auf Objective-C beschränkt, sondern unterstützt eine Vielzahl von Sprachen, einschließlich C, C ++ und Java. Doxygen ist auch nicht auf die Mac-Plattform beschränkt, z. B. läuft es auch unter Windows und Linux. Die Ausgabe von Doxygen unterstützt auch mehr als nur HTML. Sie können PDF-Ausgaben (über LaTeX) oder RTF- und Manpages generieren.

Doxygen geht auch über die reine Dokumentation hinaus. doxygen können verschiedene Grafiken und Diagramme aus dem Quellcode (siehe erstellen Punkt bezogene Optionen). Doxygen kann auch eine durchsuchbare und Syntax - Hervorhebungen Version des Codes und Querverweis erstellen , die mit der Dokumentation (die sehen Source - Browser - Optionen ' ).

Doxygen ist für kleine bis mittlere Projekte sehr schnell (die Diagrammgenerierung kann zwar langsam sein, wird jedoch heutzutage auf mehreren CPU-Kernen parallel ausgeführt und Diagramme aus einem Lauf werden im nächsten Lauf wiederverwendet). Bei sehr großen Projekten (z. B. Millionen von Codezeilen) ermöglicht doxygen, die Projekte in mehrere Teile aufzuteilen und die Teile dann wie hier erläutert miteinander zu verknüpfen .

Ein schönes Beispiel aus der Praxis für die Verwendung von Sauerstoff für Objective-C finden Sie hier .

Die Entwicklung von Sauerstoff hängt stark vom Feedback der Benutzer ab. Wir haben eine aktive Mailingliste für Fragen und Diskussionen und einen Bug-Tracker für Bugs und Feature-Anfragen.

Die meisten Benutzer von doxygen verwenden es für C- und C ++ - Code, daher haben diese Sprachen natürlich die ausgereifteste Unterstützung und die Ausgabe ist stärker auf die Funktionen und Anforderungen dieser Sprachen abgestimmt. Das heißt, auch Wünsche und Probleme mit anderen Sprachen werden ernst genommen.

Beachten Sie, dass ich fast die gesamte Sauerstoffentwicklung und die meisten Tests auf einem Mac selbst durchführe.

Ich bin der Autor von appledoc, daher ist diese Antwort möglicherweise voreingenommen :) Ich habe zwar alle genannten Generatoren (und mehr) ausprobiert, war aber frustriert, da keine Ergebnisse hervorgebracht hat, die ich haben wollte (ähnliche Ziele wie Sie).

Nach Ihren Angaben (ich erwähne nur Appledoc und Doxygen, ich erinnere mich nicht so gut an Headerdoc):

1. Konsistenter Look: Appledoc sofort einsatzbereit, andere müssen CSS optimieren, sind aber wahrscheinlich machbar.

2. Generierung von Dokumentationssätzen (für Xcode-Referenzen): Appledoc bietet sofort Unterstützung für durchsuchbare und durch Optionen anklickbare Dokumentation. Doxygen generiert XML- und Makefile-Dateien, die Sie selbst aufrufen müssen. Zusätzlich unterstützt appledoc sofort veröffentlichte Docsets .

3. Kategorien: Mit appledoc können Sie Kategorien zu bekannten Klassen zusammenführen oder getrennt lassen. Foundation- und andere Apple-Klassenkategorien werden separat in der Indexdatei aufgeführt . Sauerstoff: Das hat nicht am besten funktioniert, als ich es ausprobiert habe.

4. Benutzerdefinierte Referenzseiten: Appledoc unterstützt standardmäßig Markdown oder benutzerdefiniertes HTML. Sauerstoff: Sie können der Hauptseite benutzerdefinierte Dokumentation hinzufügen. Sie wissen nicht, ob Sie weitere Seiten hinzufügen können.

5. Einfache Befehlszeile: hängt davon ab, wie Sie es betrachten: appledoc kann alle Argumente über Befehlszeilenschalter übernehmen (unterstützt aber auch optionale Plist-Dateien für globale und Projekteinstellungen), sodass die Integration in Build-Skripte sehr einfach sein sollte. Für doxygen muss eine Konfigurationsdatei verwendet werden, um alle Parameter einzurichten.

6. Große Codebasen: Alle Tools sollten dies unterstützen, obwohl sie zeitlich nicht verglichen wurden. Ich bin mir auch nicht sicher, ob ein Tool zwischengespeicherte Werte unterstützt (die zuvor gesammelten Daten durchlaufen, um Zeit zu sparen). Ich möchte dies für die nächste Hauptversion hinzufügen.

Es ist einige Zeit her, dass ich versucht habe, andere Tools zu verwenden, daher wurden möglicherweise die oben genannten Probleme mit doxygen / headerdoc behoben! appledoc selbst hat auch Nachteile: Wie Sie bereits erwähnt haben, gibt es keine Unterstützung für Aufzählungen, Strukturen, Funktionen usw. (es wurden einige Arbeiten in dieser Richtung durchgeführt, überprüfen Sie diese Verzweigung ), und es gibt eine Reihe von Problemen , die Sie je nach Verwendung möglicherweise verhindern Deine Anforderungen.

Ich arbeite derzeit an einem wichtigen Update, das die wichtigsten Probleme abdeckt, einschließlich der Unterstützung von Aufzählungen, Strukturen usw. Ich schiebe regelmäßig neue Inhalte in den experimentellen Zweig, sobald ich größere Teile fertiggestellt und stabil genug gemacht habe, damit Sie den Anweisungen folgen können Fortschritt. Aber es ist noch sehr früh und der Fortschritt hängt von meiner Zeit ab, so dass es eine Weile dauern kann, bis die Lösung funktioniert.

Xcode 5 analysiert jetzt Ihre Kommentare, um nach Dokumentation zu suchen und diese anzuzeigen:

Sie müssen weder Appledoc noch Sauerstoff verwenden (zumindest, wenn Sie Ihre Dokumente nicht exportieren möchten). Weitere Informationen finden Sie hier