Ce Tutorial à pour but de guider les programmeurs de classes AS3 débutants ou autres, vers un standard de documentation du code que tout le monde pourra lire aisément et qui permet au moyen d’un générateur de créer un manuel d’utilisation. Il a pour but également de servir de règle minimum à la soumission de classes auprès de la rubrique (à venir)  Librairie de classes AS3.

Dans ce tutorial, il sera présenté les paramètres et balises ASDoc appliqués aux Classes écrites en AS3, pour les classes écrites en MXML, je vous renvois à la documentation ASDoc du manuel Adobe Flex.

A propos d’ASDoc

ASDoc est un outil en ligne de commande qui génère de la documentation au format HTML sur analyse de vos fichiers ActionScript commentés. L’exemple le plus connu étant la documentation de l’API, manuel de référence du langage Adobe AS3. L’outil fait partie de l’Adobe Flex SDK.

ASDoc va parser le fichier de classe et va également s’appuyer sur le compilateur mxmlc.exe (ou le compc pour les swc) pour au final générer cette documentation.

Il crée un répertoire (par défaut : asdoc-output) dans lequel il va créer les fichiers html de(s) la(les) classe(s) analysée(s) + un index ainsi qu’une liste des packages et des classes dans un total de 3 frames. Le point de départ de la doc étant l’index.html.

ASDoc génère une documentation pour tous les éléments déclarés comme public ou protected. De cette manière, une méthode, une propriété déclarée en tant que private n’apparaîtra pas dans la documentation ! Même si celle-ci possède un commentaire ASDoc en bonne et due forme. Le seul code éligible à la documentation ASDoc doit être une classe définie au sein d’un package qu’il soit anonyme ou non.

La structure minimum du code soumit doit être :

1
2
3
4
5
6

Package
{
    Public class MyClass
    {
    }
}

A quoi ressemble un commentaire ASDoc ?

Tout programmeur un peu soucieux commente son code, autant le faire dans un format qui s’avère utile par la suite! ASDoc ne reconnaît qu’un format et ignore le reste. Le structure de commentaire doit commencer par les caractères  /** et se terminer par   */ Entre ces deux balises, le commentaire peut prendre plusieurs lignes.

Exemple :

1
2
3
4
5

/**
* Commentaire principal ..
*
* @Balise directive de compilation
*/

La bonne pratique est de commencer chaque ligne par un * suivit d’un espace, suivit du contenu du commentaire, ASDoc ne tient pas compte de l’espace ni des fins de ligne et cela est plus lisible.

Où placer les commentaires ASDoc?

Le commentaire ASDoc se place juste avant l’élément à commenter. Donc, juste avant les déclarations de classe, interface, méthode, propriété. Le parser Asdoc ignore tout commentaire placé ailleurs, même si formaté ASDoc.

Exemple:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

package
{
	/**
	 * Ceci est un commentaire de classe..
	 *
	 * @author Alama
	 */
	public class MyClass
	{
		/**
		 * ceci est un commentaire de propriété..
		 */
		public var maVar:String;
 
		/**
		 * Ceci est un commentaire de méthode..
		 */
		public function MyClass()
		{
		}
	}
}

Le commentaire de Classe joue un rôle global au sein de la page HTML générée. Il défini la classe elle même. Les exemples de code d’utilisation de la classe sont à ajouter à ce niveau, cela créera un lien dans le header vers l’exemple qui sera situé en bas de page. C’est dans ce commentaire également qu’on placera la directive @private si on souhaite que ASDoc ne compile pas cette classe. On verra les balises directives plus loin dans ce tutorial.

Cas particulier des Getters et des Setters. Dans le cas où les deux existent pour une même propriété, on Commente le Getter et on place le Setter à @private. Sans quoi, on retrouverait 2 définitions pour une même propriété dans la documentation.

Exemple :

1
2
3
4
5
6
7
8
9

/**
* Indique ou défini si le TextField est au format HTML.
*/
public function get html():Boolean {}; 
 
/**
* @private
*/
public function set html(value:Boolean):void {};

Les balises HTML reconnues par ASDoc

La première ligne du commentaire constitue la définition principale. Pour ajouter des nouvelles lignes, elles devront être entourées de balises <p>..</p>, cela a pour effet de créer un nouveau paragraphe, donc espacé par une ligne vide.

Les balises reconnues en tant que ‘code’ et leur contenu formaté sont <code>, <listing> et <pre>.

La balise <code> est la plus simple et est utilisée pour insérer un mot de code dans une phrase.

Exemple :

1
2
3
4

/**
 * La fonction <code>draw()</code> dessine le PieChart
 * et doit être affiché avec <code>addChild()</code>.
 */

La balise <pre> tient compte du formatage du code, les espaces, tabulations, retours lignes, etc. et affiche le code sur fond blanc. Elle est peu utilisée en général.

La balise <listing> est une balise qui est propre à ASDoc via une classe dans l’asdoc.js et est utilisée pour des blocs de code. Elle formatera et décorera le code avec un fond grisé et ou d’autres chose selon le CSS. C’est la meilleure balise pour insérer des exemples.

Les autres balises HTML telles que <li>, <ul>, <ol> sont en général laissées telles-quelles par ASDoc mais passe au travers du parser, donc, il est très important de TOUTE les fermer !! Une erreur courante est d’oublier de fermer une balise, dans ce cas, ASDoc échoue purement et simplement.

Si, à l’intérieur d’une balise HTML, vous devez afficher des caractères comme < , > , * , etc.. Vous devez les convertir en équivalent HTML-CODE.

Vous trouverez une liste des balises autorisées de même que les HTML-CODE pour les caractères spéciaux dans le tableau récapitulatif suivant :
http://www.flashxpress.net/wp-content/uploads/2009/02/tableau_balises_html.html

Les balises directives @tag

Les balises commençant par @ sont des directives de compilation ASDoc. Elles permettent à ASDoc de structurer la documentation.

Les balises @tag se placent en dernier lieu dans le bloc de commentaire, après une ligne vide pour une question de lisibilité.

Exemple :

1
2
3
4
5
6
7

/**
 * Cette classe MyClass ..
 *
 * @author Alama
 */
public class MyClass
{

@private

Est sans doute une des plus importantes ! En présence de cette balise, ASDoc ne compile pas l’élément auquel le commentaire appartient. Si @private est placé dans le commentaire de classe, c’est toute la classe qui est ignorée et n’apparaitra pas dans la documentation. Si elle est placée au niveau d’une méthode ou une propriété, cette dernière ne sera pas dans la documentation. Elle est utile pour exclure de la doc certaines classes ou certains éléments. A ne pas confondre avec l’attribut de déclaration AS3 Private qui empêche également la compilation de l’élément dans la doc.

Attention ! Même si ce qui est défini avec @private n’est pas compilé, il n’en reste pas moins parsé par ASDoc, donc, les fautes de syntaxe AS généreront un échec de ASDoc. On peut également se servir d’une classe estampillée @private pour générer un nombre de classes précis ! Nous verrons comment, dans le tutorial appliqué à la compilation ASDoc.

Exemple :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

public class MyClass
{
	/**
	 * @private
	 */
	public var maVar:String; // La propriété maVar n'existera
                                // pas dans la documentation!
 
	/**
	 * Crée une instance MyClass ..
	 */
	public function MyClass()
	{
 
	}
 
}

@default

Spécifie la valeur par défaut d’une propriété. Asdoc converti cette balise en la phrase suivante : The default value is value

Exemple :

1
2
3
4
5
6
7
8
9
10
11
12
13
14

/**
 * Défini la couleur..
 *
 * @default 0x000000
 */
public var myVarColor:uint;
 
/**
 * Crée une instance MyClass..
 */
public function MyClass()
{
	myVarColor = 0x000000;
}

@param

Spécifie et décrit le(s) paramètre(s) passé(s) à une méthode. Le paramName doit être écrit exactement de la même manière que celui écrit dans la signature de la méthode.

Exemple :

1
2
3
4
5
6
7
8
9

/**
 * Définition..
 *
 * @param myParam
 */
public function myFunction(myParam:Boolean):void
{
	//implémentation..
}

@return

Ajoute une section retour à la description d’une méthode avec le texte défini dans la balise, ASDoc détermine automatiquement le type de retour en fonction de ce qui est typé dans l’AS.

Exemple :

1
2
3
4
5
6
7
8
9

/**
 * Définition..
 *
 * @return Hello World
 */
public function myFunction():String
{
	return "Hello World";
}

@see

Crée, soit une ancre au sein du html lui même, soit un lien vers une classe différente, soit un lien vers un membre d’une autre classe, soit un lien vers internet, etc. selon ce qu’on écrit derrière.

Attention ! Si @see est placé au sein du commentaire de classe, les liens internes vers des membres de cette classe ne fonctionne pas ! Cela ne fonctionne que vers des choses en dehors de la classe. Aussi, il ne faudra pas créer de lien vers quelque chose qui n’existe pas dans la documentation générée ! Par exemple, un lien vers la classe Array de l’API AS3 sera créé mais n’aboutira nulle part, car les dépendances du frameWork natif AS3 ne sont pas générées.

Au sein des autres commentaires (propriétés, méthodes, etc.) tous les usages de la balise @see fonctionnent y comprit les ancres internes à la classe elle-même.

Exemple :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

package
{
 
	/**
	 * Définition..
	 *
	 * @see http://www.flashxpress.net   // pointe vers une page web.
	 * @see MyClassPerso                      // pointe vers une autre classe.
	 * @see myControls.MyClassPerso#myMethod   // pointe vers une méthode
         *                                                 d'une autre classe.
	 */
	public class MyClass
	{
		/**
		 * Définition..
		 *
		 * @default 0x000000
		 * @see #myFunction        // pointe vers une fonction
                 *                           interne à la classe.
		 */
		public var myVarColor:uint;
.
.

Pour les autres possibilités de la balise @see, Voici un tableau récapitulatif :
http://www.flashxpress.net/wp-content/uploads/2009/02/tableau_balise_see.html

@exemple

Ajoute une rubrique Example dans la documentation de l’élément concerné. Attention, Si cette balise est placée dans le commentaire de classe, ASDoc le considère comme un exemple global lié à la classe. Dans ce cas, il ajoute l’exemple en bas de page HTML et il ajoute également un lien Examples dans le header de la page + un lien dans la description de classe. Si la balise est placée ailleurs, l’exemple est simplement ajouté au niveau de l’élément concerné.

Non obligatoire, la balise peut être suivie d’une phrase explicative : @exemple Ce code instancie MyClass et l’affiche sur la scène.

Le code qui suit cette balise doit être entouré d’une balise html de formatage de code, la plus conforme étant <listing>.

Exemple :

1
2
3
4
5
6

/**
 * Définition..
 *
 * @example <listing>instance.myVarColor = 0xFF0000;<listing>
 */
public var myVarColor:uint;

Correction, il faut lire : @example <listing>instance.myVarColor = 0xFF0000;<listing>

@includeExample

Souvent, les exemples ne sont pas courts, c’est souvent le cas pour les exemples d’usage de classe (ceux balisés dans le commentaire de classe), donc, pour d’une part ne pas encombrer la classe de commentaires trop volumineux et d’autre part, parce que souvent vous allez essayer votre classe en la testant dans une classe de type Main, il est plus commode de laisser les exemples dans un fichier AS séparé.

La balise @includeExample sert, comme son nom le laisse présager, à inclure un exemple depuis un fichier externe. Et les règles sont les mêmes que pour la balise @exemple. Le fichier example.as est à placer à coté du fichier AS de la classe concernée.

Exemple :

1
2
3
4
5
6
7

/**
 * Définition..
 *
 * @includeExample MyClass_usage_exemple.as
 */
public class MyClass
{

Ceci termine la présentation des balises @tag et constitue le minimum à appliquer lors de la création de vos classes. Il existe encore quelques autres balises telles que @copy qui copie le commentaire d’un élément d’une autre classe, ou encore @inheritDoc qui copie le commentaire d’une méthode d’une superClass, on l’utilise souvent pour commenter une méthode override. Ainsi que quelques autres encore..

Vous trouverez un récapitulatif des balises dans ce tableau :
http://www.flashxpress.net/wp-content/uploads/2009/02/tableau_balises_tag.html

Comment faire un fichier externe d’exemple?

Tout d’abord, il doit répondre aux mêmes exigences minimums qu’une classe normale. C’est-à-dire, une classe dans un package.

Ensuite, la classe doit être commentée en ASDoc avec la balise @private. Sans quoi, elle sera compilée et apparaîtra dans la documentation en tant que classe.

Les commentaires ASDoc insérés dans l’exemple ne sont pas générés. Cependant, si vous voulez absolument qu’un commentaire apparaisse dans l’exemple de code de la documentation, vous devez utiliser la balise @exampleText. Tout ce qui est écrit derrière cette balise sera affiché dans la documentation. Même en cas de retour ligne.

Attention !! Si vous ajoutez du commentaire ASDoc, il ne pourra y en avoir qu’un pour la définition de classe et éventuellement, un après tout le code, juste après le } de fermeture de Classe ! sans quoi, votre code sera tronqué à partir du commentaire ASDoc.

Ce qui est écrit dans le commentaire de classe apparaîtra juste au dessus du bloc de code et ce qui est écrit dans le commentaire après la classe apparaîtra juste en dessous.

Les commentaires de type //blabla.. n’apparaîtront que s’ils sont écrits dans le corps de classe.

Exemple d’une classe exemple :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

package
{
	import flash.display.Sprite;
 
	/**
	 * @private
	 * @author Alama
	 * @exampleText Cet exemple crée un pieChart avec une image
	 * qu'il va découper. L'explode est réglé à 5 pixels
	 * Et est défini en mode strict.
	 */
	public class Exemple extends Sprite
	{
 
		public function Exemple()
		{
			var chart:PieChart = new PieChart;
			chart.degree=true;
			chart.explode = 5;
			chart.explodeStrict = true;
			chart.pictureUrl = "image.jpg";
			chart.pictureFixRadius = true;
			chart.draw([90,30,30,10,10,5,5,60,50,40,30]);
			chart.x = stage.stageWidth/2;
			chart.y = stage.stageHeight/2;
			addChild(chart);
		}
 
	}
 
}

Quelques règles à suivre:

• Si un élément public n’est pas précédé d’un commentaire ASDoc, le code de cet élément apparaît dans la doc sans aucune description.
• Si un élément contient une balise @private, le code de l’élément ainsi que son commentaire sont ignorés et n’apparaissent pas dans la doc.
• Tout texte étant précédé d’une balise @tag est interprété comme étant un argument de cette balise (sauf dans le cas de @private qui empêche la sortie). Même en cas de retour ligne.
• Toute balise HTML comme <p> passera dans le parser et sera dans le html de Doc.
• Si une de ces balise HTML n’est pas fermée </p> , la génération échouera.
• Le nom du fichier, le nom de classe et le nom du constructeur doivent être rigoureusement identique sans quoi, ASDoc.exe échouera.
• Tout import de classe doit être utilisé dans le code et au minimum déclaré par ‘var instance : Classe;’ sans quoi, la génération échouera en cas de génération avec dépendances ou d’un frameWork complet.
• Les fichiers exemple.as doivent être au même niveau que la classe à laquelle ils sont dédiés.
• Les fichiers exemple.as doivent contenir un commentaire de classe ASDoc contenant une balise @private.

PS : l’utilitaire ASDoc.exe appelant le mxmlc.exe qui à son tour lance un .jar, etc. Fait que les erreurs du compilateur ne remontent pas ! Seules les erreurs de parsing remontent et son indiquées. Voilà pourquoi, en cas d’échec de la génération, il n’y a dans 90% des cas aucune info sur la provenance et il faut absolument chercher dans le code en vérifiant bien les quelques règles indiquées si haut.

Voici un exemple de documentation d’une classe et son résultat ASDoc:
http://www.covergraph.com/alama/asdoc_with_prettify/result_asdoc_tuto.jpg

Pour terminer ce tutorial

Parfois, vous vous poserez la question : « comment vais-je documenter ceci ou celà ? quelle phrase utiliser? » Le mieux est de se rapprocher de la Doc officielle Adobe AS3, n’hésitez pas à vous en inspirer! A un détail près.. Dans la doc officielle, Adobe présente ses classes en commençant par : « La classe UneTelle .. « . En effet, normalement, il n’en existe qu’une au monde.. tandis que votre classe perso, il n’y a aucune garantie qu’il y en ai pas plusieurs qui porte le même nom.. Par conséquent, il est préférable de présenter ses classes persos en commençant par : « Cette ClassePerso .. » . Evidement, si vous créez un framework qui possède un nom déposé ou connu de la communauté, vous pourriez présenter vos classe de la manière suivante : « La classe nomDuFrameWork.MaClasse ..  » ou « La classe XXX du framework XXX .. ».

Voilà, ceci clôture ce tutorial, en espérant vous avoir donné envie de documenter vos classes au format ASDoc..

Source : http://livedocs.adobe.com/flex/3/html/help.html?content=asdoc_1.html

Merci à Lunar > http://blog.lunar-dev.net/2008/06/26/formatter-ses-documentations-asdoc/ de m’avoir guidé dans mes début sur ASDoc et de m’avoir fait découvrir le @includeExample et la commande de compilation -examples-path que ma première documentation ne mentionnait pas.

Merci à Nicolas et Guylaine pour leur soutien au projet de librairie de classes AS3.