I. Description et rôle▲
L'ASDoc est à actionScript ce que la javadoc est à java. L'ASDoc contient un compileur qui permet de générer des documentations de classes ou de packages entiers à l'aide de XSLT. L'ASDoc est disponible dans le Flex SDK 3. Son intérêt est d'avoir une documentation publique permettant à toute personne voulant utiliser une classe d'avoir une notice précise et standardisée. La documentation de Flex est générée par ASDoc.
II. Documenter une classe▲
II-A. Exemple et règles▲
La documentation d'une classe répond à un certain nombre de règles.
- Pour chaque déclaration d'un élément actionScript (déclaration d'une variable, d'une constante, d'une classe, d'une méthode), ASDoc générera un élément associé dans la documentation de cette classe.
- La déclaration d'un commentaire associé à un élément se fait immédiatement avant celui-ci.
- L'écriture des commentaires doit respecter une syntaxe valide XHTML.
- Chaque nouvelle ligne du commentaire doit comporter un astérisque * ainsi qu'un espace.
Un exemple typique de documentation d'un élément (ici une méthode) :
Tous les commentaires peuvent être écrits sur plusieurs lignes. En revanche, pour obtenir des sauts de ligne et paragraphes dans la documentation finale, il est nécessaire d'utiliser des balises XHTML. Utiliser <p></p> pour générer un nouveau paragraphe. Le premier <p></p> est automatiquement associé au commentaire secondaire.
II-B. Cas des fonctions getter et setter▲
En ActionScript 3.0, certaines variables non publiques s'accompagnent de fonctions getter et setter (ou non). Afin de documenter correctement ces groupes d'éléments qui ne doivent en former qu'un seul dans la doc, certaines conventions sont à suivre.
Le principe est d'insérer le tag @private lors de la déclaration de la variable private.
Par convention, on spécifie la fonction get en premier (en effet, la fonction set peut ne pas être spécifiée si on souhaite laisser la variable en lecture seule).
On documente alors normalement la méthode getter comme si on documentait la variable, en spécifiant sa valeur par défaut par exemple. On ne met pas le tag @return, puisque ce n'est pas la méthode getter en elle-même que l'on documente.
Pour finir, on exclut la méthode setter en lui affectant le tag @private.
II-C. Tags ASDoc▲
Il est nécessaire d'utiliser un certain nombre de tags pour créer une documentation efficace. Les tags de base les plus utilisés sont :
@param
La syntaxe est : @param paramètre description du paramètre. Ce tag permet de décrire un des paramètres d'une méthode. Créer un nouveau tag pour chaque paramètre. Inclure la valeur par défaut, si celle-ci existe, dans la description.
@return
Spécifie une valeur de retour pour la méthode documentée. La syntaxe est : @return description
@default
Spécifie la valeur par défaut d'une propriété La syntaxe est : @default value
@private
Si le tag @private est présent dans un commentaire, l'élément actionScript associé ne sera pas inclus dans la documentation. Cela est utile pour retirer des méthodes ou variables privées que l'utilisateur de la classe n'a pas besoin de connaître.
@see
Ce tag permet de créer un lien. Suivant le texte qui suit le tag, le lien pourra être externe (lien http) ou interne à la documentation (lien pointant vers une autre classe de la documentation). Le nombre de possibilités est assez élevé. Cf le tableau complet ci-après.
@inheritDoc
Si ce tag est présent dans un commentaire, le compileur recherche dans les interfaces puis classes mères les occurrences de la méthode ou variable associée au commentaire, puis recopie la description principale et les tags @param et @return du commentaire trouvé dans le commentaire recevant @inheritDoc. Liste de tous les tags utilisables (en anglais) : Liste complète des tags
II-D. Balises XHTML utilisables▲
Les plus utilisés sont les balises <p>, <code> et ont le même rôle qu'en XHTML. La balise <code> est très utilisée pour formater les noms de variables, leurs valeurs, etc. À noter qu'il ne faut pas utiliser la balise <p> pour le premier paragraphe du commentaire d'un élément.
III. Génération de la documentation▲
La génération de la documentation fait appel au compileur de l'ASDoc : asdoc.exe. Celui-ci est présent dans le Flex SDK 3 à l'adresse : ${chemin_du_SDK}\bin\asdoc.exe Les templates et bibliothèques ASDoc se situent dans ${chemin_du_SDK}\asdoc\
III-A. Ressources nécessaires▲
Plusieurs manières permettent de générer notre documentation plus ou moins efficacement. La plus efficace est l'utilisation de taches ANT via eclipse, car elle nécessite peu de maintenance, mais est en revanche plus dure à mettre en place au départ, car elle nécessite des connaissances sur ANT.
La façon de procéder plus simple et malgré tout très efficace est l'utilisation de deux fichiers XML et d'un fichier .bat (sous windows) ou .sh (sous linux).
- Le fichier .bat a pour rôle d'appeler la commande système permettant de lancer le compileur..
- Un fichier xml de configuration des options à envoyer au compileur.
- Un « manifest file » de type XML décrivant les classes à inclure dans la documentation.
III-B. Emplacement des fichiers▲
Dans le cadre d'une programmation de type objet, organisée sous forme de packages, il sera judicieux de placer les fichiers précédents dans le dossier contenant tous les packages (à priori la racine du projet).
III-C. Création des fichiers▲
III-C-1. Fichier BAT▲
Voici un template de fichier bat :
Ce fichier lance le compileur ASDoc avec les options spécifiées dans le fichier xml. Il faut paramétrer la variable asdocPath (chemin vers le compileur ASDoc, dépendant de la machine utilisée). Il faut aussi paramétrer le chemin vers le xml de configuration des options du compileur. Les chemins peuvent être relatifs ou absolus. Il est conseillé de spécifier un chemin absolu pour le compileur.
III-C-2. Fichier XML de configuration▲
Ce fichier xml contient les options à passer au compileur ASDoc.
Les chemins sources à spécifier devront être en concordance avec le chemin des packages spécifiés dans le « manifest file ». Plusieurs chemins sources et namespaces peuvent être déclarés.
L'une des options importantes est namespaces.
Cependant, c'est la plus flexible. Les classes spécifiées dans les manifest files seront affectées à l'espace de nom (namespace) qui leur est associé.
L'option doc-namespaces recense les namespaces à inclure dans la documentation. Ces namespaces doivent avoir été déclarés dans l'option namespaces.
L'utilisation des namespaces est une des manières d'inclure les classes à documenter, mais il y en a d'autres (option include-classes par exemple).
Tous les chemins spécifiés peuvent être relatifs ou absolus.
III-C-3. Fichier XML manifest▲
Ce fichier recense toutes les classes appartenant à un namespace (qui sera inclus ou non dans la documentation). Ce fichier doit suivre la syntaxe suivante :
Chaque nœud component inclut une nouvelle classe. L'attribut id de ce nœud est le nom de la classe, et l'attribut class a pour valeur une chaine de caractère qui serait celle qu'on ferait pour importer cette classe (par rapport au source-path spécifié en paramètre du compileur).
Le package à spécifier doit être en concordance avec les chemins sources spécifiés dans le fichier xml de configuration du compileur..
III-D. Exemples▲
Sont joints avec ce tutoriel les templates des fichiers précédents. Voici un exemple d'utilisation de ces templates, afin de comprendre comment les paramétrer. Il permet de générer la documentation de toutes les classes du package lunarlib.utils
L'arborescence de notre exemple est la suivante :
Et voici les fichiers crées en conséquence :
build-documentation.bat :
doc-config.xml :
Le source-path est spécifié comme étant à deux niveaux supérieurs, ainsi, les classes spécifiées dans le manifest file ci-dessous concordent.
Le paramètre output est également deux niveaux supérieurs, afin de créer un dossier docs dans lequel sera générée la documentation.
asdoc-manifest.xml :
Le manifest file contient la liste des classes à inclure dans la documentation. Ces fichiers sont joints au tutoriel, ainsi que la documentation générée.
IV. Maintenance▲
Lorsque l'ajout de nouvelles classes est à faire, il suffit de les ajouter dans le fichier manifest. Éventuellement, lorsque les packages deviennent nombreux, d'autres espaces de nom peuvent être créés, et dans ce cas, un nouveau fichier manifest doit leur être associé.