Forums Développement Multimédia

Les formations Mediabox
Les formations Mediabox

ASDoc : Générateur de documentation Actionscript

Compatible ActionScript 3. Cliquer pour en savoir plus sur les compatibilités.Compatible Flex 2. Cliquer pour en savoir plus sur les compatibilités.

Vue d'ensemble

AsDoc est un outil en ligne de commande utilisé pour créer de la documentation HTML à partir de fichiers AS ou MXML.
Le rendu HTML est semblable à la documentation de référence de Flex 2.

Téléchargement et installation

Suivez ces étapes pour utiliser ASDoc :

- Si vous n'avez pas installé Flex Builder™ 2 ou Flex 2 SDK, faites le maintenant.

- Téléchargez asdoc.zip et prenez connaissance de la licence d'utilisation.

- Dézippez asdoc.zip dans le dossier raçine du SDK. Par exemple, si Flex Builder 2 est installé dans C:\Program Files\Adobe\Flex Builder 2, dézippez asdoc.zip dans le dossier C:\Program Files\Adobe\Flex Builder 2\Flex SDK 2. Sur MAC OS X, assurez-vous de ne pas remplacer les dossiers existants.

- Vous devriez maintenant avoir asdoc.exe (et asdoc pour MAC OS X) dans le dossier du SDK. Cet exécutable s'utilise de la même manière que mxmlc.exe et compc.exe. Pour en savoir plus sur l'utilisation d'asdoc.exe, reportez-vous aux sections Exemples et Documentation ci-dessous.

Exemples

Le dossier asdoc\examples contient un fichier exécutable .bat et un fichier .sh pour chacun des deux exemples.

asdoc_corelib exécute asdoc sur corelib, une des API ActionScript 3.0 libres disponibles sur Adobe Labs. Les fichiers .bat et .sh utilise la commande asdoc doc-sources pour effectuer une recherche récursive de tous les fichiers source et les documenter. Cette commande modifie également les titres principaux et les titres de la fenêtre, fournit des noms de package et place les pages de la documentation dans le dossier asdoc\examples\corelib-asdoc.

asdoc_flexstore exécute asdoc sur une portion de flexstore, un des applications principales de Flex. Cet exemple montre des fichiers MXML et AS légèrement documentés. Les fichiers .bat et .sh utilisent les commandes asdoc source-path et doc-classes pour définir une classe et ses dépendances au document. Cette commande change également le titre de la fenêtre et place les pages de la documentation dans le dossier asdoc\examples\flexstore-asdoc.

Documentation

En plus de cette page, nous avons écrit deux guides pour vous aider à utiliser ASDoc :

  • Utiliser ASDoc : Explique de façon détaillée comment utiliser AsDoc et contient la liste de tous les paramètres d'ASDoc.
  • Créer des commentaires pour ASDoc : Montre comment créer des commentaires dans les fichiers AS et MXML pouvant être analysés par l’outil asdoc.

Problèmes connus

Il existe deux limitations à la version actuelle :

  • ASDoc fonctionne uniquement sous MAC OS X et Windows. En raison de l’utilisation d’un exécutable (asDocHelper), il ne peut pas être utilisé sous d’autres systèmes d’exploitation. A long terme, Adobe espère porter le code exécutable en Java. A plus court terme, la prochaine version devrait fonctionner sous Linux.
  • Les composants MXML ne peuvent pas être entièrement documentés. Ils apparaîtront dans les pages HTML obtenues en sortie, mais il n’est pas possible en MXML d’ajouter des commentaires au niveau des classes ni sur les variables qui représentent les composants.

ASDoc n’ayant pas été complètement testé, il existe encore certainement des bugs cachés. Voici la liste des problèmes connus :

  • Des lignes vierges apparaissent sur la console de sortie lors de l’exécution d’AsDoc.
  • Lorsqu’on documente une propriété getter/setter avec des métadonnées Bindable qui n’ont pas de cible ([Bindable ()]), cette propriété est toujours définie en lecture seule dans ASDoc. Les métadonnées Bindable qui n’ont pas de cible dans une classe rendent toutes les propriétés de cette classe invisibles.
  • Sous Mac OS X, les paramètres comportant des espaces ne peuvent pas être utilisés en ligne de commande. Utilisez un fichier de configuration et le paramètre load-config pour ces valeurs.
  • Il n’est pas possible d’exclure des sources lorsque vous utilisez include-sources.
  • Si vous utilisez @includeExample, le SWF n’apparaît pas dans la page de sortie.
  • Les commentaires non-ASCII ne sont pas correctement analysés, même avec l’ensemble actionscript-file-encoding.
  • Le message d’erreur “The definition is in circular inheritance” (la définition est en héritage circulaire) s’affiche parfois en utilisant doc-sources. Cette erreur disparaît si l'on utilise la commande doc-classes.