Générateurs de documentation Objective-C: HeaderDoc vs Doxygen vs AppleDoc
J'ai besoin de mettre en œuvre une solution de génération de documentation pour mon lieu de travail et je l'ai limitée aux trois mentionnées dans le titre. J'ai pu trouver très peu d'informations sur les comparaisons formelles entre ces solutions, et j'espère que ceux d'entre vous ayant une expérience dans une ou plusieurs des solutions ci-dessus pourront peser:
Voici ce que j'ai pu glaner de ma passe initiale:
HeaderDoc Pros: cohérent avec les documents existants d'Apple, compatibilité avec la création de Apple docsets
Inconvénients de HeaderDoc: Difficile de modifier le comportement, le projet n'est pas activement travaillé, beaucoup l'ont abandonné (ce qui signifie qu'il doit y avoir quelque chose de déficient, bien que je ne puisse pas le quantifier).
Avantages Doxygen: communauté de support active b/c de large base d'utilisation, très personnalisable, la plupart des types de sortie (comme le latex, etc.)
Contre Doxygen: Prend du travail pour le rendre cohérent avec les documents sur les pommes, la compatibilité avec Apple docsets n'est pas aussi simple
AppleDoc Pros: semble cohérent avec les documents existants d'Apple, compatibilité avec la création de Apple docsets,
Inconvénients AppleDoc: problème avec la documentation des typedefs, des énumérations et des fonctions, en cours de développement
Cela semble-t-il précis? Notre solution souhaitée aura:
- Aspect et toucher cohérents avec la référence de classe objective-c des pommes
- Possibilité de cliquer sur une option pour afficher la référence de la documentation à partir de Xcode, puis lier au document (tout comme les classes d'Apple)
- Gestion intelligente des catégories, des extensions et similaires (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 peut inclure des images et être lissable à partir des références de classe générées de manière transparente, comme la façon dont la référence de classe UIViewController d'Apple établit un lien vers la page liée.
- Commandes en ligne de commande faciles à exécuter qui peuvent être intégrées dans des scripts de construction
- Gestion gracieuse d'une très grande base de code
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.
En tant que créateur et développeur principal de doxygen, permettez-moi également de donner mon point de vue
(évidemment biaisé aussi ;-)
Si vous recherchez une réplique 100% fidèle du style de documentation d'Apple, AppleDoc est un meilleur choix à cet égard. Avec doxygen, vous aurez du mal à obtenir exactement le même look, donc je ne recommanderais pas d'essayer.
En ce qui concerne les ensembles de documents Xcode; Apple fournit instructions comment configurer cela avec doxygen (écrit au moment où Xcode 3 a été publié). Pour Xcode 4 il y a aussi un Nice guide comment intégrer doxygen.
Depuis la version 1.8.0, doxygen prend en charge Markdown markup , ainsi qu'un grand nombre de commandes markup supplémentaires.
Avec doxygen, vous pouvez inclure de 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 à l'aide de doxygen. En plus de cela, 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 en entrée. Vous pouvez générer un modèle avec des valeurs par défaut à l'aide de doxygen -g ou utilisez un éditeur graphique pour en créer et en éditer un. Vous pouvez également diriger des options via doxygen via un script en utilisant doxygen - (voir la question 17 de la FAQ pour un exemple)
Doxygen n'est pas limité à 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, par ex. il fonctionne également sur Windows et Linux. La sortie de Doxygen prend également en charge plus que du HTML; vous pouvez générer PDF (via LaTeX) ou RTF et pages de manuel).
Doxygen va également au-delà de la pure documentation; doxygen peut créer divers graphiques et diagrammes à partir du code source (voir les options connexes dot ). Doxygen peut également créer une version navigable et mise en évidence de la syntaxe de votre code, et une référence croisée avec la documentation (voir les options connexes navigateur source ).
Doxygen est très rapide pour les projets de petite à moyenne taille (la génération de diagramme peut être lente cependant, mais de nos jours s'exécute sur plusieurs cœurs de processeur 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 peut ensuite lier les parties ensemble comme je l'ai expliqué ici .
Un bel exemple concret d'utilisation de doxygen pour Objective-C peut être trouvé ici .
Le développement de doxygen dépend fortement des commentaires des utilisateurs. Nous avons un liste de diffusion actif pour les questions et discussions et un bug tracker pour les bugs 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 la sortie est plus adaptée aux fonctionnalités et aux besoins de ces langages. Cela dit, les souhaits et les problèmes avec d'autres langues 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.
Je suis l'auteur de appledoc, donc cette réponse peut être biaisée :) J'ai quand même essayé tous les générateurs mentionnés (et plus), mais je suis frustré car aucun résultat n'a été souhaité (objectifs similaires à vous).
Selon vos points (je ne mentionne que appledoc et doxygen, je ne me souviens pas très bien de headerdoc):
Look cohérent: appledoc hors de la boîte, autre besoin de Tweak css, mais probablement faisable.
Génération d'ensembles de documentation (pour les références Xcode): prise en charge complète des appledoc pour une documentation consultable et cliquable en option, doxygen génère du xml et un makefile que vous devez invoquer vous-même. De plus, appledoc prend en charge ensembles de documents publiés prêts à l'emploi.
Catégories: appledoc vous permet de fusionner des catégories avec des classes connues ou de les laisser séparées, fondations et autres Apple sont répertoriées séparément dans fichier d'index =. doxygen: cela ne fonctionnait pas mieux quand je l'ai essayé.
Pages de référence personnalisées: appledoc prend en charge prêt à l'emploi en utilisant Markdown ou HTML personnalisé, doxygen: vous pouvez inclure une documentation personnalisée sur la page principale, je ne sais pas si vous pouvez inclure plus de pages.
Ligne de commande facile: dépend de la façon dont vous la regardez: appledoc peut prendre tous les arguments via des commutateurs de ligne de commande (mais prend également en charge les fichiers plist de paramètres globaux et de projet facultatifs), il devrait donc être très facile à intégrer avec les scripts de construction. doxygen nécessite l'utilisation du fichier de configuration pour configurer tous les paramètres.
Grandes bases de code: tous les outils devraient supporter cela, bien qu'ils ne se comparent pas dans le temps. Je ne sais pas non plus si un outil prend en charge les valeurs mises en cache (en cours d'exécution sur des données précédemment collectées afin de gagner du temps) - je cherche à l'ajouter pour la prochaine version majeure.
Cela fait un moment que j'ai essayé d'utiliser d'autres outils, donc les problèmes mentionnés ci-dessus avec doxygen/headerdoc peuvent avoir été résolus! appledoc lui-même a également des inconvénients: comme vous le mentionnez, il n'y a pas de support pour les énumérations, les structures, les fonctions, etc. (il y a eu du travail dans ce sens, vérifiez cette fourchette ), et il a son propre ensemble de problèmes qui peut vous empêcher de l'utiliser, selon vos besoins.
Je travaille actuellement sur une mise à jour majeure qui couvrira la plupart des problèmes flagrants , y compris le support pour les énumérations, les structures, etc. Je pousse régulièrement de nouvelles choses vers la branche expérimentale dès que je termine de plus gros morceaux et le rend stable assez, pour 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 avant de trouver une solution.
Xcode 5 va maintenant analyser vos commentaires pour rechercher de la documentation et l'afficher:
Vous n'avez plus besoin d'utiliser appledoc ou doxygen (du moins lorsque vous ne souhaitez pas exporter vos documents). Plus d'informations peuvent être trouvées ici