Générer une documentation intégrée à Xcode avec appledoc

Si vous utilisez pas mal le documentation intégrée à Xcode ou les infos contextuelles d’un éléments dans le code, vous serez certainement intéressé par cet article qui vous explique en détail comment générer une documentation pour vos classes ou frameworks.

En effet, il est possible d’ajouter à Xcode de nouveaux paquets de documentation via une url ou un fichier.
Cet article est rédigé pour la configuration Mac OS X Lion et Xcode 4.3 minimum.
La génération de la documentation s’effectue en trois étapes : installation du générateur, description de la documentation et génération de la documentation.

Installation du générateur

L’outil appledoc est développé par Gentle Bytes et n’a rien à voir avec Apple comme son nom pourrait l’indiquer. Pour l’installer, rendez-vous sur le dépôt de Tomaz, téléchargez le fichier ZIP de la dernière version et décompressez-le sur votre machine.
Lancez un Terminal (pas par la fenêtre) et tapez la commande suivante dans votre dossier décompressé :

sudo sh install-appledoc.sh 

Si une erreur apparait vous informant que le dossier Developern’a pu être trouvé, il faut indiquer au système où il se trouve par la commande :

/usr/bin/xcode-select -switch /Applications/Xcode.app/Contents/Developer

Relancez ensuite la commande d’installation et tout devrait fonctionner.
Si vous n’avez pas de chance et que la commande ne marche pas, appledoc n’a pu être installé dans le dossier par défaut, essayez d’installer appledoc avec la commande suivantes :

sudo sh install-appledoc.sh -b /usr/bin -t ~/Library/Application\ Support/appledoc

Vous êtes alors prêt à utiliser appledoc !

Description de la documentation

Pour pouvoir générer votre documentation, il faut décrire le fonctionnement de vos méthodes dans les fichiers d’entête. Un commentaire commence toujours par un slash et 2 étoiles. Il termine par une étoile et un slash.

/**
* Mon commentaire
*/

Un saut de ligne se traduit par l’ajout d’une ligne vide commençant par une étoile simplement.
Le premier paragraphe du commentaire correspond à la description de la méthode, les suivants seront affichés dans la section Discussions de la documentation de la méthode.
Pour écrire en gras, entourez votre mot ou expression d’une étoile (*). Pour l’italique, entourez le mot d’un souligné (_). Une zone de code se traduira par un apostrophe inverse (`).
Commenter une classe
Pour documenter une classe, il faut ajouter votre texte avant la déclaration de l’interface dans le fichier .h.
Commenter une méthode
Les commentaires d’une méthode peuvent contenir plusieurs informations comme une description générale, une discussion, la description des paramètres (@param), la description du retour de la fonction (@return) ou encore des méthodes liées (@sa).
Prenons un exemple :

/** 
 * Create a human readable distance string.
 *
 * Values are rounded to the next round value for the right unit.
 *
 * `Example: with _distanceInMeters_ = 1245, the result will be @"± 1 km".`
 * @param distanceInMeters Distance in meters to convert to string.
 * @sa getDistanceFromValue:withFormat:
 * @sa getDistanceFromValue:withFormat:forDistanceUnit:
 * @returns Returns a string with distance.
 */

Create a human readable distance string. sera la description de la méthode.
Values are rounded to the next round value for the right unit. `Example: with _distanceInMeters_ = 1245, the result will be @ »± 1 km ».` se trouvera dans la partie Discussions de la méthode (la seconde phrase sera affichée en format code).
@param distanceInMeters Distance in meters to convert to string.Déclaration d’un paramètre suivi du nom de la variable suivi de la description de la variable.
@sa getDistanceFromValue:withFormat: See also, voir aussi; définit les méthodes liées à la méthode décrite. Format court, on n’indique pas les noms des variables.
@returns Returns a string with distance. décrit le retour qui sera donné par la méthode.
Groupe de méthodes
Il est possible, comme dans la documentation traditionnelle de Xcode, de définir des groupes de méthodes. La commande suivante est placée entre deux méthode comme « séparateur ».

/** @name Phone numbers formatting */

Voilà pour les grandes lignes de l’art du commentaire. Si vous en voulez un peu plus, visitez la page dédiée sur le site de l’éditeur.

Génération de la documentation

Dernière étape, la génération de la documentation. Etape assez simple en apparence mais qui demande un peu de configuration.
Retournez dans votre Terminal et saisissez la commande suivante en ayant étudié les paramètres à modifier.

appledoc --project-name "Nom de la documentation" --project-company "Mon entreprise" --company-id com.acme.bestdoc --no-repeat-first-par --output docset_folder --ignore .m .

Il faut spécifier le nom de votre documentation, le nom de votre entreprise, l’ID (utile si vous prévoyez de déployer des mises à jour via le web).
Le paramètre no-repeat-first-par indique au compilateur que la première ligne d’une description ne doit pas être répétée dans la section Discussions.
Le compilateur lit l’intégralité de vos fichiers (excepté les .m dans notre cas, ils sont ignorés), génère un fichier DocSet et l’installe automatiquement dans le centre de documentation de Xcode.

Vous pouvez retrouver le fichier docset dans le dossier /Users/benoit/Library/Developer/Shared/.
Le détail des paramètres utilisables avec la commande appledooc est accessible sur la page dédiée.

Xcode
Xcode 
v11.4 - 7.5 Go - Gratuit 
Apple

Auteur: Benoit DELDICQUE

Actuellement en poste sur Strasbourg, je suis en charge de la conception et la réalisation d'applications iOS pour iPhone, iPad et iPod touch.

Articles similaires

Commentaires fermés.