Auto-documentation : HeaderDoc, Doxygen, ...

Réponses

• Greensource Membre

  juin 2009 21:36 modifié #2

  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 Membre, Modérateur

  juin 2009 21:36 modifié #3

  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 Membre, Modérateur

  juin 2009 juin 2009 modifié #4

  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 Membre

  juin 2009 21:36 modifié #5

  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 Membre

  septembre 2009 21:36 modifié #6

  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 Membre

  avril 2010 avril 2010 modifié #7

  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.

  3609_.zip 1.1K
• 6ix Membre

  avril 2010 21:36 modifié #8

  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 Membre, Modérateur

  avril 2010 21:36 modifié #9

  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 Membre

  avril 2010 décembre 2010 modifié #10

  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.

  3964_.zip 1.1K
• Flo Membre

  avril 2011 21:36 modifié #11

  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 Membre

  avril 2011 21:36 modifié #12

  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 Membre

  avril 2011 21:36 modifié #13

  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 Membre, Modérateur

  avril 2011 21:36 modifié #14

  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 Membre

  avril 2011 21:36 modifié #15

  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 Membre

  avril 2011 21:36 modifié #16

  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 Membre, Modérateur

  avril 2011 21:36 modifié #17

  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