Ce tutorial entre dans le cadre du projet de librairie de classes AS3 de FlashXpress, mais il peut également être utile à tout un chacun. Il s’agit plus d’un manuel que d’un tutorial à proprement parlé et à pour but de fournir un outil permettant à ceux qui souhaitent soumettre une classe, de compiler de façon simple et rapide, leur documentation avant de proposer leur code final à flashXpress.

Il fait suite au tutorial Commenter ses Classes AS3 au format ASDoc dans lequel on apprend à commenter son code afin qu’il soit éligible au compilateur asdoc.exe.

Il a pour autre but de fournir des fichiers qui permettront à tout le monde de formater sa documentation telle qu’elle le sera dans la rubrique Librairie de Classes AS3.

Tous les fichiers  qui sont abordés sont téléchargeables en fin de tutorial.

A propos d’asdoc.exe

Le fichier asdoc.exe est un utilitaire en ligne de commande, fourni avec le Flex SDK, qui génère de la documentation ASDoc. Il s’appuie sur plusieurs fichiers du FrameWork, tel que le mxmlc.exe, le compc.exe, le globalPlayer.swc, plusieurs .jar et surtout un template relativement complexe qui va servir de modèle de documentation.

Pour générer une documentation, il faut ouvrir une fenêtre DOS et le lancer avec des paramètres pour stipuler quelle(s) classe(s) il doit compiler, où placer la doc, etc.

Exemple :
asdoc -source-path C:\flex\class_dir -doc-classes comps.GraphingWidget comps.GraphingWidgetTwo

Vous trouverez sur ce lien, un tableau récapitulatif des commandes de compilation:
http://www.flashxpress.net/wp-content/uploads/2009/02/tableau_commandes_asdoc.html

ASDocGUI

Très rapidement, l’idée m’est venue de me faire un petit programme tout simple pour ne pas chaque fois utiliser le système en ligne de commande. Certes, il existe déjà un GUI du nom de ASDocGEN.exe open source, mais au moment où je me suis plongé dans tout ça, la page n’aboutissait nulle part et de plus, cela présentait un générateur pour Classes AS2.

La page d’AsDocGen : http://osflash.org/asdocgen

Il est à noté que l’éditeur Open Source Flash Develop 3.0 contient également ce GUI, dans ses outils, et est compatible AS3.

ASDocGUI est donc un petit programme, pour Windows,  sans prétention, qui n’a pour ambition que de lancer asdoc.exe dans un thread séparé en background et lui passer les bons paramètres.

Il n’y a pas grand-chose à en dire, son utilisation est simple. Les deux premiers champs sont éditables, le premier reprendra le contenu pour le placer comme Titre dans le header de la documentation et le deuxième fait pareil, en pied de toutes les pages HTML générées.

Pour générer une documentation d’une seule classe, il faut laisser les options par défaut et cliquer sur Parcourir afin de sélectionner le fichier .as à compiler. Ce sera le cas le plus courant des gens qui veulent proposer une Classe à la rubrique Librairie de classes AS3 de FlashXpress. Attention, elle doit être en package anonyme.

Par défaut, le compilateur asdoc.exe crée un répertoire asdoc-output au même niveau que la classe sélectionnée. Vous pouvez choisir un autre emplacement en cliquant sur Parcourir, asdoc.exe créera les fichiers html dans le répertoire sélectionné. Attention de choisir un répertoire vide, car le contenu sera vidé avant la génération.

Si vous cochez Documenter les dépendances toutes les classes persos dépendantes seront générées également. Il s’agit des classes utilisateur importées, les classes AS3 natives ne sont pas générées.

Si vous cochez Documenter un FrameWork, asdoc.exe va générer une documentation de toutes les classes contenues dans le répertoire sélectionné et celles de tous les sous-répertoires. L’arborescence des répertoires sera l’arborescence des packages dans la documentation. Vous devez sélectionner le répertoire « toplevel » de votre framework.

Si vous possédez un framework compilé au format SWC et dont des classes sont utilisées dans vos dépendances, vous pouvez ajouter le répertoire contenant le ou les SWC dans le Champ Répertoire de librairies SWC supplémentaire.

La vérification en mode Strict s’adresse au compilateur mxmlc.exe et va générer un échec de la génération en cas de variable non définie ou problème de typage, etc. Exactement pareil que dans votre éditeur de code. Si vous avez codé et compilé votre code en mode strict, il ne devrait pas y avoir de problème à la génération de documentation.

Comme je le mentionnais dans le tutorial Documenter ses Classes AS3 au format ASDoc, l’utilitaire en ligne de commande n’indique pas les erreurs émanant du mxmlc. En général, il interrompt la génération et se ferme purement et simplement. Les erreurs ne remontant pas dans la console DOS, le GUI est incapable de les communiquer. Seules, les erreurs émanant du parser sont signalées. Il s’agit souvent d’une balise html non fermée comme </p> manquant ou ce genre de chose.

Quelques sources d’échec de la génération

• Les champs Titre et Pied de page contiennent des caractères spéciaux. Les seuls caractères acceptés sont alphanumériques.
• Le répertoire de destination existe déjà et un de ses fichiers est ouvert dans un programme.
• Les noms du fichier, de la classe et du constructeur ne sont pas identiques.
• En cas de génération d’une seule classe, la package n’est pas anonyme.
• En cas de génération d’un FrameWork, les noms du package et des répertoires ne sont pas identiques par rapport au répertoire TopLevel.
• En cas de génération avec dépendances ou de FrameWork, une classe importée n’est pas déclarée dans le code.

Comment générer une ou plusieurs classe(s) d’un FrameWork

J’entends par framework plusieurs classes et souvent définies dans des packages différents. La génération à l’aide de l’option Documenter un framework va générer la totalité des classes qui ne porte pas la balise @private. Dans son Utilisation par défaut, La génération d’une seule classe oblige qu’elle soit en package anonyme.

Pour contourner ce manque de souplesse, on va utiliser une classe qu’on va écrire exclusivement dans le but de générer une documentation. Et on va utiliser ASDocGUI en mode Classe unique et cocher la case Documenter les classes dépendantes. L’astuce consiste à faire une classe qui ne contient que des imports avec déclarations et on va tout simplement la baliser @private afin qu’elle ne fasse pas partie de la documentation.

Les classes que j’importerai dans cette classe seront compilées. On peut également les importer toutes et commenter celles qu’on ne veut pas compiler.

Cette Classe spéciale doit se trouver à coté du répertoire racine du FrameWork, dans notre exemple, la racine est un répertoire nommé my. la classe doit être déposée, non pas dedans, mais au même niveau.

Sa structure sera :

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

package
{
 
	/**
	 *  @private
	 */
	internal class FrameworkClasses
	{
 
	}
 
}

Imaginons que nous avons un framework constitué comme ceci :

my.controlsObjects.PieChart
my.controlsObjects.Gallery
my.remoting.Responder
my.utils.TextUtil

A présent, on veut générer la documentation de my.remoting.Responder uniquement :

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

package
{
 
	/**
	 *  @private
	 */
	internal class FrameworkClasses
	{
		import my.remoting.Responder; Responder;
	}
 
}

Pour compiler tout le framework sauf la classe Responder, je peux également faire :

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

package
{
 
	/**
	 *  @private
	 */
	internal class FrameworkClasses
	{
              import my.controlsObjects.PieChart; PieChart;
              import my.controlsObjects.Gallery; Gallery;
              //import my.remoting.Responder; Responder;
              import my.utils.TextUtil; TextUtil;
	}
 
}

Une fois la classe terminée, il suffit d’utiliser ASDocGUI par défaut en cochant la case Générer les classes dépendantes et  sélectionner cette classe par parcourir..

La présentation de ASDocGUI est à présent terminée, vous pouvez le télécharger dans la partie « téléchargements » en fin de tutorial.

Colorisation du code présent dans la documentation

Au début, en cherchant des infos sur ASDoc, je suis tombé sur un article d’Ekameleon qui explique comment modifier son template pour coloriser le code à l’aide de Google Prettify Open Source :

http://www.ekameleon.net/blog/index.php?post/2008/03/14/94-use-asdoc-with-google-prettify

Ce qui m’a donné l’envie d’intégrer cela à mon template.. Malheureusement, une fois les modifs terminées, pas de chance, ça ne marchait pas chez moi ! Sans doute la version de mon Prettify est plus récente. De plus, avec mon pote Jirotoh, on aurait aimé intégrer ça à la doc locale de AS3. Donc, retour à zero et Après quelques recherches, Jirotoh à trouvé le moyen de l’intégrer directement dans le asdoc.js et de lui faire prendre en compte directement les balise <code> et <pre> des pages Html. :D

Avantages, en remplaçant le asdoc.js de n’importe quelle documentation, tout le code se colorise ! Même sur une doc déjà faite. J’y ai ajouté une liste de tous les keywords AS3 (ou presque) afin d’obtenir la colorisation la plus complète possible.

Le fichier asdoc.js prettify est téléchargeable en fin de tutorial accompagné de son css.

Adaptation du template ASDoc aux couleurs de FlashXpress

Une autre modification a été celle du CSS et de quelques images du template afin que la doc générée réponde aux spécifications de la nouvelle rubrique Librairie de Classes AS3 de FlashXpress.

Pour ceux qui trouvent ce look plus joli, ils peuvent récupérer l’asdoc_fxp.zip dans la partie Téléchargements  afin de les remplacer dans la documentation locale de Flash. Adresse typique :

C:\Program Files\Fichiers communs\Adobe\Help\fr_FR\AS3LCR\Flash_10.0

Les fichiers à changer sont: asdoc.js, style.css et copier le contenu du répertoire images dans le répertoire images existant de la doc.

Téléchargements

Pour ceux qui ont déjà le Flex SDK installé.
Le fichiers ASDocGUI.exe est à placer dans le répertoire racine du Flex SDK.
http://www.covergraph.com/alama/asdoc_with_prettify/ASDocGUI.rar

Pour ceux qui n’ont pas Flex SDK ou qui veulent le FrameWork complet de génération ASDoc. A décompresser où vous voulez et créer un raccourci de asdocgui.exe vers le bureau ou menu programmes.
Ceci comprend, tout les fichiers nécessaires à la création d’une documentation, les fichiers pour coloriser le code automatiquement et le CSS aux couleur FXP.
http://www.covergraph.com/alama/asdoc_with_prettify/ASDocFXP.zip

Les fichiers asdoc.js et style.css pour coloriser la doc en gardant le look d’origine.
http://www.covergraph.com/alama/asdoc_with_prettify/AsDoc_mod_pretty.zip

Sources

L’article « prettify » d’Ekameleon :
http://www.ekameleon.net/blog/index.php?post/2008/03/14/94-use-asdoc-with-google-prettify

L’article « Coloriser ASDoc » de Lunar :
http://blog.lunar-dev.net/2008/06/26/formatter-ses-documentations-asdoc/

Google Prettify :
http://code.google.com/p/google-code-prettify/

Adobe Flex ASDoc :
http://livedocs.adobe.com/flex/201/html/wwhelp/wwhimpl/common/html/wwhelp.htm?context=LiveDocs_Book_Parts&file=asdoc_127_1.html

Remerciements

Je tiens à remercier,

Jirotoh, pour son aide et son travail sur le CSS et les fichiers JavaScript du template.
Ekameleon, pour ses réponses à mes questions et m’avoir laissé monopoliser les commenatires de son Blog :P
Lunar, pour ses réponses à mes questions et  » Sorry » pour le nombre de commentaires.. :D
Nicolas et Guylaine, pour leur soutien.