Auto-documentation : HeaderDoc, Doxygen, ...

AliGator

Bonjour à  tous,

J'ouvre ce fil pour causer un peu des outils d'auto-documentation, c'est à  dire l'utilisation des commentaires formatés dans votre code (devant chaque classe, méthode, etc), pour la génération automatique de documentation HTML (ou autre) ensuite.

Voilà  déjà  quelques constatations, puisque je suis en plein dedans :

HeaderDoc
J'étais parti dans un premier temps sur HeaderDoc pour commenter mon projet actuel, pour la simple et bonne raison qu'il est inclus avec les DevTools et que bon y'a des Scripts pour insérer les commentaires tout faits dans le menu Scripts, me suis dit, allons-y...
Mais j'avoue que j'ai été bien déçu au final :

• Template de base moche et pas aquicheur, ça donne pas super envie
  
• Possibilite de customiser la TableOfContents (masterTOC)... mais pas la mise en page de chaque page, ni ajuster le frame, etc...!!
  
• De même il y a quelques styles CSS qui trainent à  gauche à  droite insérés dans les fichiers générés (donc le code est en dur dans le script perl, j'ai fouillé :crackboom:- ), mais vraiment pas suffisamment pour personnaliser le résultat complètement
  

Donc au final autant dire qu'on peut quasiment rien customiser... et que le résultat obtenu est pas super "glamour" 

Doxygen
Du coup j'ai fini par me rabattre vers mon bon vieil ami Doxygen, que j'avais déjà  utilisé mais y'a de cela un sacré bout de temps...

Pour l'instant de ce que j'en ai vu ça me semble plutôt prometteur pour un usage de documentation de projet iPhone, puisque :

• j'ai eu l'agréable surprise de voir (même si j'en doutais peu vu comme le projet est plutôt actif et très utilisé) qu'il supportait l'Objective-C, et même l'Objective-C 2.0.
  
• il est parfaitement customisable (styles CSS, fichiers de template, ...) " je le savais déjà  mais c'est bon à  rappeler " mais en plus les templates de base sont déjà  bien plus agréables que ceux de HeaderDoc, donc à  la limite c'est même pas utile d'y toucher, c'est déjà  "friendly".
  
• Le binaire précompilé (pour Leopard) est téléchargeable directement sous forme d'image disque DMG sur le site... et en plus inclus une GUI pour configurer tout ce qu'il faut (avec les commentaires sur ce à  quoi sert chaque option), sauver la config, carger une config, lancer la génération... Ce qui est vachement plus agréable que de se taper le fichier de config Doxyfile à  la main !
  
• Il sait générer des "DocSets", c'est à  dire que si vous le demandez dans le fichier de conf, il va créer un Makefile pour générer un bundle ".docset" qui sera exploitable par l'outil d'Aide intégré à  Xcode... de la même manière que la doc Apple !
  

Donc déjà , pas mal de qualités pour Doxygen, moi qui pensait qu'Apple fournissant HeaderDoc c'était l'outils qu'ils utilisaient voire conseillaient, en fait, pas tant que ça... Ils ont même une page sur l'ADC consacrée à  la génération de DocSets avec Doxygen, donc bon, ça me semble l'outil le plus adapté finalement


Soucis avec Doxygen et les @protocols
Il me reste juste un problème auquel j'ai été confronté avec Doxygen, c'est la création de liens vers des méthodes de protocoles. C'est à  dire que si j'écris :

/*! Doxygen comment.<br />  this method calls currentClassMethodWithParam1:param2: with 0 as a second parameter.<br />  it then calls OtherClass#methodOfAnotherClass: , then notifies its delegate by calling<br />  MyMachinDelegate#currentClass:didDoSomethingWithParam1:andParam2: .<br />*/

Et bien les liens vont bien automatiquement être créés (conformément à  la doc de doxygen) pour les 2 premiers, mais pas pour [tt]MyMachinDelegate#currentClass:didDoSomethingWithParam1:andParam2:[/tt]... à  priori uniquement parce que MyMachineDelegate est un @protocol et qu'il ne semble reconnaà®tre que les méthodes extraites des @interface pour générer les liens... Ou alors il y a une syntaxe particulière pour désigner le protocole, mais j'ai fait 2-3 tests et j'ai rien trouvé... Si y'en a par miracle qui ont une idée...



Voilà , si vous avez une réponse quant à  mon problème déjà  je suis prenneur, et sinon d'autres suggestions d'outils d'autodoc, même si jusqu'à  présent j'en ai pas testé beaucoup mais doxygen est prometteur (je l'aimais déjà  du temps où je l'utilisais, mais je ne l'avais jamais utilisé avec de l'Objective-C).

Sinon j'ai pas regardé du côté des générateurs de DocBook (format XML assez universaire du moins commun pour décrire une doc, a vocation d'être transformé par exemple par un XSL pour la mise en forme ensuite)... je me demande si Doxygen le gère pas en fait ?

Voilà , vos avis sont les bienvenus

Greensource

Perso j'ai testé surtout Headerdoc pour l'instant et j'en suis arrivé aux même conclusions. Mais alors il y a un truc que je ne comprends pas du tout. Comment diable Apple fait-elle pour avoir une doc aussi jolie et bien foutu? Ils ont leur propre Headerdoc ou quoi?
Parce que quand on regarde la nouvelle doc de l'API iPhone 3.0 et bien elle claque quand même!

Pour ce qui est de Doxygen il faudrait que je mis mette mais j'ai toujours eu l'impression que c'était pas très bien organisé.

AliGator

Oui c'est aussi ce qui m'a étonné... Au début je pensais qu'Apple utilisait HeaderDoc pour générer ses docs, mais plus ça va plus j'en doute. D'autant que tout ce qui est génération de DocSets non plus n'est pas dispo, etc...

Alors qu'avec Doxygen c'est tout à  fait possible de faire qqch qui ressemble à  la Doc Apple. Rien qu'en le lançant directement sur un code bien commenté on arrive à  un truc sympa... et après ce n'est qu'une question de template à  personnaliser.

Et puis quand je regarde les headers des frameworks Apple par exemple, les commentaires dans le code sont formattés différemment selon les frameworks, c'est bizarre : certains sont juste des commentaires simples "// blah" non formattés, d'autres sont des commentaires à  la doxygen, genre "/*! ... */", avec les mots clés doxygen-like... mais dont les commentaires dans le header ne correspondent pas à  ceux trouvés dans la doc !!

D'ailleurs c'est très dommage vu que j'espérais trouver la réponse à  ma question en inspectant les headers de frameworks comme WebKit.framework, pour lequel j'avais vu dans la doc un lien vers une méthode de delegate (donc d'un @protocol), donc j'ai voulu aller voir comment ils mettaient dans dans les commentaires de code mais que dalle...

AliGator

En attendant j'ai mis en pratique l'intégration dans Xcode, en adaptant à  ma sauce le script qu'a pondu Apple.
Moi je lis le fichier Doxyfile et j'en extrait les informations (où est généré la doc, où est le Makefile, quel est le nom du docset généré...), plutôt que de les  écraser (dans une copie du fichier Doxyfile / Doxygen.config copiée dans /tmp) comme le fait Apple.

Voilà  donc le script que j'utilise à  ce jour, si ça peut servir.
Il suffit donc de créer un nouveau "Target" de type "Shell Script Target", et de copier/coller ce script dans la phase "Run Script" de ce nouveau target. Il vous suffira alors de "builder" ledit target pour générer la documentation Doxygen, et générer puis ouvrir le DocSet dans Xcode (s'il a été configuré de le générer dans le Doxyfile)

DOXYGEN_PATH=/Applications/Doxygen.app/Contents/Resources/doxygen<br />DOXYFILE=$SOURCE_ROOT/../Doxyfile<br /><br /># Test if Doxygen is installed and can be found<br />if ! [ -x &quot;$DOXYGEN_PATH&quot; ] ; then<br />	echo Documentation Generation:0: error: You must install Doxygen first, see http://www.doxygen.org/download.html#latestsrc<br />	exit 1<br />fi<br /><br /># Create a generic Doxyfile if it does not exist yet<br />if ! [ -f &quot;$DOXYFILE&quot; ] ; then <br />  echo doxygen config file does not exist, creating a generic one.<br />  &quot;$DOXYGEN_PATH&quot; -g &quot;$DOXYFILE&quot;<br />fi<br /><br /># Retrieve some info from the Doxyfile (and strip quotes if present)<br />DOC_OUT_DIR=$(sed -ne s/&quot;OUTPUT_DIRECTORY[ &#092;t]*=[ &#092;t]*&#092;(.*&#092;)&quot;/&quot;&#092;1&quot;/p &quot;$DOXYFILE&quot; | sed -e s/&#092;&#092;&#092;&quot;//g)<br />HTML_OUT_DIR=$(sed -ne s/&quot;HTML_OUTPUT[ &#092;t]*=[ &#092;t]*&#092;(.*&#092;)&quot;/&quot;&#092;1&quot;/p &quot;$DOXYFILE&quot; | sed -e s/&#092;&#092;&#092;&quot;//g)<br />DOCSET_ID=$(sed -ne s/&quot;DOCSET_BUNDLE_ID[ &#092;t]*=[ &#092;t]*&#092;(.*&#092;)&quot;/&quot;&#092;1&quot;/p &quot;$DOXYFILE&quot; | sed -e s/&#092;&#092;&#092;&quot;//g)<br /><br />MAKEFILE_PATH=${DOC_OUT_DIR}/${HTML_OUT_DIR}<br />DOCSET_PATH=${DOC_OUT_DIR}/${HTML_OUT_DIR}/${DOCSET_ID}.docset<br /><br /><br /><br /># Generate the documentation<br />&quot;$DOXYGEN_PATH&quot; &quot;$DOXYFILE&quot;<br /><br /><br /># Build the docset<br />if [ -f &quot;${MAKEFILE_PATH}&quot;/Makefile ]; then<br />	echo<br />	echo === Generating DocSet... ===<br />	echo Documentation Generation:0: note: Generating DocSet...<br />	echo<br /><br />	make -C &quot;${MAKEFILE_PATH}&quot;/<br />	osascript -e &quot;tell application &#092;&quot;Xcode&#092;&quot; to load documentation set with path &#092;&quot;${DOCSET_PATH}&#092;&quot; with display&quot; # Load the docset and display it<br />else<br />	echo Documentation Generation:0: warning: The DocSet generation was not configured in the Doxyfile: the DocSet will not be generated.<br />fi

L'avantage étant là  encore (comme pour ce que j'ai fait pour les tests U dans l'autre post) l'intégration dans Xcode et donc aussi des "Message Bubbles". Par exemple dans mes commentaires formattés pour Doxygen, si j'ai une erreur, un tag Doxygen non reconnu par exemple, j'ai une "Message Bubble" dans Xcode à  l'endroit de mon commentaire qui pose problème, etc

zoc

J'utilise aussi la solution doxygen intégrée à  XCode depuis un petit moment (mais avec un script amélioré, pas par moi, par rapport à  celui de la note d'Apple).

Et l'avantage de l'apparition des bubbles, c'est d'obliger à  commenter correctement, parce que sinon ça devient vite un foutoir illisible (avec plein de bulles partout)

accessoirement, comme je dispose également d'un serveur sur lequel tourne Mercurial et redmine, je génère toutes les nuits la doc doxygen de mes projets et l'intègre automatiquement dans redmine.

6ix

Je me suis plongé quelque peu du côté de Doxygen pour documenter un futur projet, et après quelques recherches je suis tombé sur Doxyclean, un script permettant de formater la doc générée par Doxygen dans un style beaucoup plus proche de ce que fait Apple.

Par contre j'avoue ne pas trop savoir comment m'en servir, malgré plusieurs tentatives, découvrant également Doxygen.

J'espère que cela intéressera ceux qui ne connaissaient pas, pour les autres, vous sauriez comment utiliser Doxyclean ?

Greensource

Bon je me suis un peu penché sur ce problème. Pour le moment j'ai mis en place une solution manuelle mais qui fonctionne et qui ressemble vraiment à  une belle documentation Apple pour le coup!

• Ecrire la doc, bas ouais c'est pas magique non plus.
  Bon par contre j'ai ajouter à  XCode un petit textmacro pour écrire plus facilement la doc doxygen. Je vous file le fichier en pièce jointe
  
• Installer Doxygen et Doxyclean
  
• Générer la documentation via Doxygen en format XML.
  
• Ce placer dans le répertoire xml crée par Doxygen
  
• Executer la commande: path_de_doxyclean/doxyclean.py
  
• Votre documentation Apple-like ce trouve dans le répertoire html
  

A terme je compte faire une version automatisé pour XCode et dans le même temps ajouter une génération docset.
A noter également qu'il y a un gros souci avec la génération de doc pour les protocols, ya pas la doc des fonctions 

Voilà 

ps: Le textmacro est à  installer ici: ~/Library/Application Support/Developer/Shared/Xcode/Specifications
Et il faut redémarrer XCode pour qu'il en tienne compte.

6ix

dans 1272443037:

Bon je me suis un peu penché sur ce problème. Pour le moment j'ai mis en place une solution manuelle mais qui fonctionne et qui ressemble vraiment à  une belle documentation Apple pour le coup!

J'en étais arrivé à  la même chose que toi, à  savoir une solution manuelle pour aboutir finalement à  une belle documentation Apple-like. C'est vrai que l'idée de pouvoir automatiser tout ça serait pas mal !

AliGator

Il suffirait de faire un script shell (enfin de modifier le script Shell proposé par Apple ou celui que j'ai posté plus haut) pour automatiser le tout.
Le script en question permet de générer la doc directement depuis Xcode (créer un target "Generate Documentation" avec une phase de type "Run Script" et y mettre le script shell de génération de doc dedans, et comme ça il suffit de faire un "Build" sur ce target pour générer la doc), après ni le mien ni celui d'Apple utilisent doxyclean, donc faudrait juste intégrer ça dedans.


GreenSource : Moi je n'ai pas de soucis pour la documentation des méthodes de mes @protocol !

Greensource

Bien, j'ai réussi à  faire un truc qui tourne chez moi. C'est déjà  bien plus automatisé même si c'est largement améliorable.
Il reste notamment une étape manuelle que j'essaierais plus tard de supprimer.
Je tiens aussi à  préciser qu'il y a peu de "sécurité" dans mon script je dois bien avouer que c'est pas ma spécialité ;-)

Voici ce qu'il faut faire:

• Installer doxyclean dans le répertoire: ~/bin/doxyclean
  
• Créer un Doxyfile avec Doxygen GUI.
  Il vous faut générer au moins en HTML et XML. Ne pas oublier de sélectionner l'option Generate Docset, sans quoi la compilation échouera.
  Le répertoire d'output doit-être PROJECT_PATH/Doxygen_output.
  Pour créer le Doxyflie, il faut faire sauvegarder, c'est pas la peine de faire run par contre.
  Bon ça c'est le gros point que je voudrais automatiser, mais il n'est à  faire qu'une seule fois.
  
• Intégration à  XCode:
  Créez une nouvelle target de type: "Shell Script Target". Double cliquez sur "Run Script" pour éditer le script. Collez-y le script suivant:
  

  #!/bin/sh
  
  # Vars
  DOXYCLEAN_PATH=$HOME'/bin/doxyclean'
  DOC_OUTPUT_DIR='./build/Documentation'
  TEMP_DOXYGEN='./Doxygen_output'
  
  # Generate xml documentation
  /opt/local/bin/doxygen Doxyfile
  
  # Backup all file to creta later the docset
  mkdir ${TEMP_DOXYGEN}/docset_temp
  cp ${TEMP_DOXYGEN}/html/Makefile ${TEMP_DOXYGEN}/docset_temp
  cp ${TEMP_DOXYGEN}/html/Info.plist ${TEMP_DOXYGEN}/docset_temp
  cp ${TEMP_DOXYGEN}/html/Nodes.xml ${TEMP_DOXYGEN}/docset_temp
  cp ${TEMP_DOXYGEN}/html/Tokens.xml ${TEMP_DOXYGEN}/docset_temp
  
  # Transform Doc into html output
  ${DOXYCLEAN_PATH}/doxyclean.py --input=${TEMP_DOXYGEN}/xml/ --output=${TEMP_DOXYGEN}/xml
  
  # Create a folder for Doc and move created file into
  if [ ! -e ${DOC_OUTPUT_DIR} ]
  then mkdir -p ${DOC_OUTPUT_DIR}
  else rm -rf ${DOC_OUTPUT_DIR}/*
  fi
  
  mv ${TEMP_DOXYGEN}/xml/html/* ${DOC_OUTPUT_DIR}/
  mv ${TEMP_DOXYGEN}/docset_temp/* ${DOC_OUTPUT_DIR}/
  
  # Make the docset
  make -C ${DOC_OUTPUT_DIR}
  
  # Load Docset in XCode
  osascript -e "tell application \"Xcode\" to load documentation set with path \"$PROJECT_DIR/build/Documentation\" with display"
  
  # Clean
  rm -rf ./Doxygen_output
  rm -f ${DOC_OUTPUT_DIR}/Makefile
  rm -f ${DOC_OUTPUT_DIR}/Info.plist
  rm -f ${DOC_OUTPUT_DIR}/Nodes.xml
  rm -f ${DOC_OUTPUT_DIR}/Tokens.xml

  
  
• Voilà  vous n'avez plus qu'à  builder cette target
  

Je vous joint également une nouvelle version de la textmacro car l'autre posait des souci de génération.

Flo

Bonjour,

je remonte ce sujet pour essayer de glaner d'éventuels retours sur l'intégration de Doxygen avec XCode.

Comme beaucoup j'ai tenté HeaderDoc, ça allait un moment, et puis j'ai vraiment eu envie de passer à  autre chose
Je me tourne alors vers mon forum de dév mac préféré et je tombe sur ce poste intéressant qui soulève néanmoins quelques questions :

- Existe-t-il depuis un outil qui permet d'intégrer doxygen directement dans XCode de manière automatisé ?
- Si non, quelqu'un a-til bidouillé dans son coin une petite solution qui me permettrait de ne pas m'arracher les cheveux sur une config longues et douloureuse ?

Merci d'avance ! 

FKDEV

Pour moi les activités de rédaction de doc ne sont pas du même ordre que les activités de codage.
Les commentaires sont destinés à  expliquer le code localement alors que la doc doit donner une vue plus génerale, plus synthetique. Expliquer les principes, donner des exemples, insister sur les points essentiels et ignorer les fonctions triviales.
tout ce que l'on a du mal à  faire avec les commentaires de code.
Si une doc doit se lire comme du code, je ne vois pas l'intérêt de la faire. Autant lire le code.

Utiliser doxygen, c'est de l'escroquerie.
Le seul cas où l'utilisation d'un outil de génératin de doc peut se justifier c'est la fourniture d'une api. Et encore.

Ma solution :
1/ ouvrir un traitement de texte
2/ Se mettre dans la peau de quelqu'un qui ne connait pas le projet
3/ Expliquer comment ça marche (quitte à  faire des diagrammes)
4/ Détailler les paramètres des principales méthodes publiques.
5/ Décrire le fonctionnement dynamique des processus les plus importants.

Mais bon, en general une partie de ce travail est deja faite quand j'ecris le code. Apres j'ai plus qu'a mettre à  jour les noms de fonctions ou les paramètres qui ont pu changer.

Greensource

Je suis assez d'accord avec toi FKDEV mais il n'empêche que ça pourrais être sympa de pouvoir crée une vrai doc intégré a XCode ( un docset).
D'ailleurs je me suis souvent demander comment le faire en utilisant Doxygen???

Pierre

AliGator

Heu Pierre, je t'avais filé mon script pour générer un docset directement avec Doxygen depuis Xcode, tu l'as repris également plus haut, donc c'est possible, non ?

FKDEV

dans 1301752030:

Je suis assez d'accord avec toi FKDEV mais il n'empêche que ça pourrais être sympa de pouvoir crée une vrai doc intégré a XCode ( un docset).

Certes.

Dans ce cas c'est juste un péché d'orgueil.  >:D

Greensource

Oui Ali mais ce que je veux dire c'est qu'on peux pas vraiment créer des Programming Guide par exemple. On peux pas aller très au delà  de la description d'API.

AliGator

Bah heu si.
Regarde ma doc de AliJSONRPC j'ai de la doc pour chaque classe ET des pages génériques d'explication des principes du framework :P

Le .h qui décrit, en langage doxygen, toutes les pages de doc non attachées spécifiquement à  une classe donnée