Objectif-c générateurs de Documentation: 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 réduit aux trois mentionnés dans le titre. J'ai été en mesure de trouver très peu d'information sur la façon de faire des comparaisons officielles entre ces solutions, et j'espère que ceux d'entre vous qui ont de l'expérience dans un ou plusieurs des domaines ci-dessus pourront donner leur avis:
Voici ce que j'ai pu glaner de mon premier passage:
Headerdoc Pros: Cohérent avec les docs existants d'apple, compatibilité avec la fabrication de Docs apple
Headerdoc contre: difficile de modifier le comportement, le projet n'est pas activement travaillé, beaucoup se sont détournés (ce qui signifie qu'il doit y avoir quelque chose de défectueux, bien que je ne puisse pas le quantifier).
Doxygen Pros:
Communauté de soutien actif b / c de base d'utilisation large, très personnalisable, la plupart des types de sortie (comme latex etc)
Doxygen Cons:
Il faut du travail pour le faire paraître/se comporter compatible avec les docs de pomme, la compatibilité avec les docs de pomme n'est pas aussi simple
AppleDoc Pros:
Semble compatible avec les docs existants d'apple, compatibilité avec la fabrication de Docs d'apple,
AppleDoc Cons:
Problème avec la documentation des typographies ,des énums, et des fonctions, activement en cours de développement
est-ce exact? Notre solution désirée aura:
- aspect et toucher cohérents avec les pommes objectif-référence de Classe C
- possibilité d'option-Cliquez pour extraire la référence de documentation de l'intérieur de Xcode, puis lien vers le doc (tout comme les classes d'apple)
- Smart manipulation des catégories, des extensions et des autres (même des catégories personnalisées de la pomme de classes)
- possibilité de créer nos propres pages de référence (comme cette page: chargement... qui peut inclure des images, et être liable à partir des références de classe générées de façon transparente, comme les liens de référence de la classe UIViewController d'apple vers la page liée.
- commandes en ligne de commande faciles à exécuter pouvant être intégrées dans les scripts de construction
- manipulation gracieuse de codes de très grande taille
sur la base de toutes les informations ci-dessus, est-ce que l'une des solutions ci-dessus est nettement meilleure que les autres? Toute suggestion ou information à ajouter serait extrêmement appréciée.
3 réponses
en tant que créateur et développeur principal de doxygen, permettez-moi également de fournir mon point de vue
(évidemment biaisé aussi ;-)
si vous recherchez une réplique fidèle à 100% du style de documentation D'Apple, AppleDoc est un meilleur choix à cet égard. Avec doxygen vous aurez du mal à obtenir ce même look, donc je ne recommande pas d'essayer.
en ce qui concerne les docsets Xcode; Apple fournit instructions comment configurer cela avec doxygen (écrit dans le temps Xcode 3 a été libéré). Pour Xcode 4 Il ya aussi un guide agréable comment intégrer doxygen.
depuis la version 1.8.0, doxygen prend en charge Markdown markup , ainsi qu'un grand nombre de commandes supplémentaires markup .
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 sous-sections. En fait, le manuel d'utilisation de doxygen a été entièrement écrit en utilisant doxygen. En outre, vous pouvez grouper des classes ou des fonctions ensemble (en utilisant @defgroup et @ingroup) et à l'intérieur d'une classe faire 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 créer et éditer une. Vous pouvez également utiliser les options de pipe 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 langues, y compris C, C++, et Java. Doxygen n'est pas non plus limité à la plate-forme Mac, par exemple, il fonctionne sous Windows et Linux. La sortie de Doxygen prend également en charge plus que le HTML; vous pouvez générer la sortie PDF (via LaTeX) ou RTF et les pages de manuel.
Doxygen va aussi au-delà de la documentation pure; doxygen peut créer divers graphiques et diagrammes à partir du code source (voir le point options connexes). Doxygen peut également créer une version browsable et en surbrillance syntaxique de votre code, et faire des références croisées avec la documentation (voir les options source browser connexes).
Doxygen est très rapide pour les projets de petite à moyenne taille (la la génération de diagrammes peut être lente, mais de nos jours fonctionne sur plusieurs cœurs CPU en parallèle et les graphiques d'une série sont réutilisés dans la prochaine série). Pour les très grands projets (par exemple des millions de lignes de code) doxygen permet aux projets d'être divisé en plusieurs parties et peut ensuite relier les parties ensemble comme je l'ai expliqué ici .
un bel exemple réel d'utilisation de doxygen pour L'Objectif-C peut être trouvé ici .
Le développement de doxygen dépend fortement de la rétroaction des utilisateurs. Nous avons une mailing list active pour les questions et les discussions et un bug tracker pour les bogues et les requêtes de fonctionnalités.
la plupart des utilisateurs de doxygen l'utilisent pour le code C et c++, donc naturellement ces langues ont le support le plus mature et la sortie est plus à l'écoute des fonctionnalités et des besoins pour ces langues. Cela dit, également des souhaits et des questions avec d'autres langues sont prises au sérieux.
notez que je fais presque tout le développement de doxygen et la plupart des tests sur un Mac moi-même.
je suis l'auteur de appledoc, donc cette réponse peut être biaisée :) j'ai essayé tous les générateurs mentionnés bien (et plus) mais je me suis frustré car aucun produit des résultats que je voulais avoir (objectifs similaires que 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 out of the box, autre besoin de modifier css, mais probablement faisable.
-
génération d'ensembles de documentation (pour les références Xcode): appledoc support complet pour la documentation interrogeable et cliquable en option, doxygen xml génère et makefile que vous devez invoquer vous-même. En outre appledoc prend en charge docsets publiés out of the box.
-
catégories: appledoc vous permet de fusionner les catégories à des classes connues ou les catégories "foundation" et "other apple class" sont énumérées séparément dans le index file . ça ne marchait pas mieux quand je l'ai essayé.
-
Personnaliser les pages de référence: appledoc prend en charge hors de la boîte, en utilisant soit des réductions ou code html personnalisé, doxygen: vous pouvez inclure des documents à la page principale, je ne sais pas si vous pouvez inclure d'autres pages.
-
ligne de commande facile: dépend de la façon dont vous le regardez: appledoc peut prendre tous les arguments par des commutateurs de ligne de commande (mais prend également en charge les paramètres globaux optionnels et les dossiers de projet plist) de sorte qu'il devrait être très facile à intégrer avec des scripts de construction. doxygen nécessite l'utilisation du fichier de configuration pour configurer tous les paramètres.
-
grands codebases: tous les outils devraient soutenir cela, bien que ne pas comparer temps. Aussi ne sais pas si tout outil prend en charge la mise en cache valeurs (en cours d'exécution sur les données précédemment collectées afin de gagner du temps) - je cherche à ajouter ceci pour la prochaine version majeure.
Cela fait un certain temps que j'ai essayé d'utiliser d'autres outils, donc les problèmes mentionnés ci-dessus avec doxygen/headerdoc ont pu être 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 structures, les fonctions, etc (il y a eu du travail fait dans ce sens, vérifier cette fourchette ), et il a sa propre ensemble de questions qui peut vous empêcher de l'utiliser, en fonction de vos besoins.
je travaille actuellement sur une mise à jour majeure qui couvrira les questions les plus criantes , y compris le soutien pour les émulsions, les structures, etc. Je pousse régulièrement de nouveaux trucs dans la branche expérimentale dès que je finis les gros morceaux et les rends assez stables, pour que vous puissiez suivre les progrès. Mais il est encore très tôt et le progrès dépend de mon temps, donc il peut prendre un certain temps jusqu'solution de travail.
