Générateurs de documentation Objective-C : HeaderDoc vs. Doxygen vs. AppleDoc

Question

Je dois mettre en œuvre une solution de génération de documentation pour mon lieu de travail et j'ai réduit mon choix aux trois solutions mentionnées dans le titre. J'ai pu trouver très peu d'informations sous forme de comparaisons formelles entre ces solutions, et j'espère que ceux d'entre vous qui ont de l'expérience avec une ou plusieurs de ces solutions pourront m'éclairer :

Voici ce que j'ai pu glaner lors de mon premier passage :

Avantages de HeaderDoc : Cohérence avec les documents existants d'Apple, compatibilité avec la création de documents d'Apple.
Inconvénients d'HeaderDoc : difficile de modifier le comportement, le projet n'est pas activement travaillé, beaucoup l'ont délaissé (ce qui signifie qu'il doit y avoir quelque chose de déficient, bien que je ne puisse pas le quantifier).

Avantages de Doxygen : Communauté de soutien active grâce à une large base d'utilisation, très personnalisable, la plupart des types de sortie (comme latex, etc.).
Inconvénients de Doxygen : Il faut travailler pour que l'apparence et le comportement soient cohérents avec les documents d'Apple, la compatibilité avec les documents d'Apple n'est pas aussi simple.

Avantages d'AppleDoc : Apparence cohérente avec les documents existants d'Apple, compatibilité avec la création de documents d'Apple,
Cons. d'AppleDoc : Problème avec la documentation des typedefs, enums et fonctions, en cours de développement.

Cela vous semble-t-il exact ? La solution que nous souhaitons aura :

• Une apparence cohérente avec la référence de classe objective-c des pommes
• Possibilité de cliquer sur l'option pour afficher la référence de la documentation à partir de Xcode, puis de créer un lien vers la documentation (comme les classes d'Apple).
• Gestion intelligente des catégories, des extensions, etc. (même des catégories personnalisées des classes d'Apple)
• Possibilité de créer nos propres pages de référence (comme cette page : Chargement qui peuvent inclure des images et être liées de façon transparente à partir des références de classe générées, comme la référence de classe UIViewController d'Apple qui renvoie à la page liée.
• Commandes en ligne de commande faciles à exécuter et pouvant être intégrées dans des scripts de construction.
• Gestion gracieuse d'un très gros codebase

Sur la base de toutes les informations ci-dessus, l'une des solutions ci-dessus est-elle clairement meilleure que les autres ? Toute suggestion ou information à ajouter serait extrêmement appréciée.

Answer 1

En tant que créateur et développeur principal de doxygen, permettez-moi d'apporter mon point de vue.
(évidemment biaisé aussi ;-)

Si vous recherchez une réplique 100% fidèle du style de documentation propre à Apple, alors AppleDoc est un meilleur choix à cet égard. Avec doxygen, vous aurez du mal à obtenir exactement le même style, donc je ne vous recommande pas d'essayer.

En ce qui concerne les jeux de documents Xcode, Apple fournit les éléments suivants instructions comment configurer cela avec doxygen (écrit à l'époque de la sortie de Xcode 3). Pour Xcode 4, il existe également un bon guide comment intégrer doxygen.

À partir de la version 1.8.0, doxygen prend en charge les éléments suivants Balisage Markdown ainsi qu'un grand nombre d'autres balisage des commandes.

Avec doxygen, vous pouvez inclure la documentation sur la page principale (@mainpage) ainsi que sur les sous-pages (en utilisant @subpage ou @page). À l'intérieur d'une page, vous pouvez créer des sections et des sous-sections. En fait, le manuel d'utilisation de doxygen a été entièrement écrit en utilisant doxygen. En outre, vous pouvez regrouper des classes ou des fonctions (en utilisant @defgroup et @ingroup) et, à l'intérieur d'une classe, créer des sections personnalisées (en utilisant @name).

Doxygen utilise un fichier de configuration comme entrée. Vous pouvez générer un modèle avec des valeurs par défaut en utilisant doxygen -g ou utiliser un éditeur graphique pour en créer et en modifier un. Vous pouvez également faire passer des options par doxygen via un script en utilisant doxygen - (voir la question 17 du FAQ pour un exemple)

Doxygen n'est pas limité à l'Objective-C, il prend en charge un large éventail de langages, notamment C, C++ et Java. Doxygen n'est pas non plus limité à la plate-forme Mac, il fonctionne également sous Windows et Linux. La sortie de Doxygen ne se limite pas à l'HTML ; vous pouvez générer une sortie PDF (via LaTeX) ou RTF et des pages de manuel.

Doxygen va également au-delà de la documentation pure ; doxygen peut créer divers graphiques et diagrammes à partir du code source (voir l'onglet point ). Doxygen peut également créer une version navigable et avec coloration syntaxique de votre code, et faire des références croisées avec la documentation (voir l'option navigateur source options connexes).

Doxygen est très rapide pour les projets de petite et moyenne taille (la génération de diagrammes peut toutefois être lente, mais elle fonctionne aujourd'hui sur plusieurs cœurs de CPU en parallèle et les graphiques d'une exécution sont réutilisés dans l'exécution suivante). Pour les très gros projets (par exemple, des millions de lignes de code), Doxygen permet de diviser les projets en plusieurs parties et de relier ces parties entre elles comme je l'ai expliqué. aquí .

Vous trouverez un bel exemple concret d'utilisation de doxygen pour Objective-C aquí .

Le développement de doxygen dépend fortement des commentaires des utilisateurs. Nous avons un programme actif de liste de diffusion pour des questions et des discussions et un Traceur de bogues pour les bogues et les demandes de fonctionnalités.

La plupart des utilisateurs de doxygen l'utilisent pour le code C et C++, donc naturellement ces langages ont le support le plus mature et le résultat est plus orienté vers les fonctionnalités et les besoins de ces langages. Cela dit, les souhaits et les problèmes concernant d'autres langages sont également pris au sérieux.

Notez que je fais moi-même presque tout le développement de doxygen et la plupart des tests sur un Mac.

Answer 2

Je suis l'auteur d'appledoc, donc cette réponse peut être biaisée :) J'ai essayé tous les générateurs mentionnés (et d'autres encore) mais j'ai été frustré car aucun ne produisait les résultats que je voulais avoir (objectifs similaires aux vôtres).

Selon vos points (je ne mentionne que appledoc et doxygen, je ne me souviens pas très bien de headerdoc) :

1. Apparence cohérente : appledoc est prêt à l'emploi, d'autres doivent modifier les css, mais c'est probablement faisable.

2. Génération d'ensembles de documentation (pour les références Xcode) : appledoc prend entièrement en charge la documentation consultable et cliquable en option, doxygen génère le xml et le makefile que vous devez invoquer vous-même. De plus, appledoc supporte documents publiés hors de la boîte.

3. Catégories : appledoc vous permet de fusionner les catégories à des classes connues ou les laisser séparées, les fondations et autres catégories de classes de pommes sont listées séparément dans fichier index . doxygen : cela ne fonctionnait pas au mieux lorsque je l'ai essayé.

4. Pages de référence personnalisées : appledoc soutient prêt à l'emploi en utilisant soit markdown soit le html personnalisé, doxygen : vous pouvez inclure la documentation personnalisée à la page principale, je ne sais pas si vous pouvez inclure plus de pages.

5. Ligne de commande facile : cela dépend de la façon dont vous le regardez : appledoc peut prendre tous les arguments par le biais de commutateurs de ligne de commande (mais supporte également les fichiers plist optionnels de paramètres globaux et de projets), il devrait donc être très facile à intégrer avec les scripts de construction. doxygen nécessite l'utilisation d'un fichier de configuration pour définir tous les paramètres.

6. Bases de code volumineuses : tous les outils devraient prendre en charge cette fonction, mais nous n'avons pas comparé les délais. Je ne suis pas non plus certain qu'un outil prenne en charge les valeurs mises en cache (en exécutant les données précédemment collectées afin de gagner du temps) - je cherche à ajouter cette fonctionnalité pour la prochaine version majeure.

Cela fait un certain temps que je n'ai pas essayé d'utiliser d'autres outils, donc les problèmes mentionnés ci-dessus avec doxygen/headerdoc ont peut-être été résolus ! appledoc lui-même a aussi des inconvénients : comme vous le mentionnez, il n'y a pas de support pour les enums, les structs, les fonctions, etc, Vérifiez cette fourche ), et il a sa propre série de problèmes qui peuvent vous empêcher de l'utiliser, selon vos besoins.

Je travaille actuellement sur une mise à jour majeure qui couvrir les problèmes les plus flagrants y compris le support des enums, structs, etc. Je pousse régulièrement de nouveaux éléments vers la branche expérimentale dès que j'ai terminé les plus gros morceaux et que je les ai rendus suffisamment stables, afin que vous puissiez suivre les progrès. Mais il est encore très tôt et les progrès dépendent de mon temps, donc cela peut prendre un certain temps jusqu'à ce que la solution fonctionne.

Answer 3

Xcode 5 analysera désormais vos commentaires pour rechercher de la documentation et l'afficher :

Vous n'avez plus besoin d'utiliser appledoc ou doxygen (du moins quand vous ne voulez pas exporter vos docs). Plus d'informations peuvent être trouvées aquí

Answer 4

Tout d'abord, un avertissement : je n'ai jamais utilisé HeaderDoc ou AppleDoc. Cependant, j'ai beaucoup utilisé doxygen et je vous recommande de l'utiliser. C'est un excellent système de documentation et il peut certainement gérer les trois derniers points de votre liste de solutions souhaitées (bien que je ne comprenne pas bien vos deuxième, troisième et quatrième points - pourriez-vous les clarifier ?)

En ce qui concerne vos trois premiers points, c'est le look que vous essayez d'obtenir. este ? Si c'est le cas, je suis sûr que vous pouvez faire une approximation avec doxygen, bien que, comme vous le dites, cela demande un certain travail. Vous pourriez créer un fichier CSS personnalisé et modifier certaines options de cofiguration o utiliser le XML généré par doxygen .