Documentar tus proyectos de Actionscript 3 con ASDoc

Algo imprescindible en cualquier proyecto grande o en el que vayan a participar varias personas es tener el código comentado, de manera que todo el mundo pueda comprender la funcionalidad de cada clase, y de sus propiedades y funciones. De igual manera, es posible con ciertas herramientas generar automaticamente la documentación de nuestras clases y proyectos en formato HTML (O el que queramos) similar a la documentación de la referencia de Actionscript o similares. Todo gracias a ASDoc, el equivalente a JavaDoc en el mundo de Flash/Flex.

Desde la versión 2.01 de Flex, Adobe ha incluido asdoc, una utilidad que genera la referencia html de los comentarios que hemos puesto en el código. Esta fue usada para generar, por ejemplo, la referencia de Actionscript 3.

Los comentarios de ASDoc empiezan por /** y acaban por */ (en Flex Builder los distinguirán porque se vuelven azules en lugar del acostumbrado verde), y necesariamente van justo antes de la definición en el código de una clase, propiedad, método. En ellos podemos escribir código xhtml normal, con sus <b></b> para negrita, párrafos encerrados en etiquetas <p></p>, ya que aunque saltemos de línea en el comentario de flex, en el html se verá como una línea y entidades html cuando tengamos que usar símbolos como < (&lt) o @(&#64 , ya que se usa para poner tags).

Cada nueva línea del comentario en AS3 empieza por un asterisco y un espacio (para mayor legibilidad).

Después de la descripción, se pueden poner tags que cumplen diferentes funciones. Algunos son estos:

• @private - impide que una propiedad o método aparezca en la explicación html porque si no se especifica ningún comentario, ni este tag, aparecerá de todas formas.
  
• @param Describe el parámetro de un método.
  
• @return Describe el valor devuelto de un método, aunque la clase del valor devuelto aparecerá de todas formas.
  
• @default Explica el valor predeterminado de una propiedad.
  
• @see Referencia hacia otro elemento de la clase, otra clase (del mismo paquete o de otro distinto) o hacia un sitio externo.
  
• @example Enuncia un ejemplo de uso del elemento que comentemos. El código que vayamos a poner en el ejemplo va entre etiquetas <listing version="3.0" ></listing>
  

Ahora podemos crear un nuevo proyecto en FlexBuilder que tenga una carpeta examples, y en ella las carpetas packageone y packagetwo. En cada una de ellas creamos una clase de Actionscript como estas:

Código :

package examples.packageone
{
   import flash.utils.*

   import mx.controls.Button;
   /** Aquí se describe la clase. Este comentario tendrá que estar DEBAJO de las
    * sentencias <i>import</i> y sobre la declaración de la clase.
    * 
    * <p>En los comentarios de asdoc
    * pueden usarse etiquetas xhtml, pero cada párrafo debe estar en 
    * sus correspondientes etiquetas, pero los caácteres html que querramos usar de
    * forma literal deberán estar escritos con su representación html,
    * por ejemplo &gt; será el símbolo mayor qué. </p> */
   public class CommentedClassExample
   {
      /**Esta propiedad es privada, de modo que este comentario no será parseado por
       * asdoc.*/
      private var noComments:String;
      
      /** La descripción de esta propiedad tampoco será visible, ya que usamos el tag:
       * @private
       * Si no lo pusiese, se vería una descripción vacía de la propiedad. */
      public var myUncommentedProperty:String;
      
      public var myLazyProperty:String;//El comentario de esta variable se verá en blanco
      
      /** La descripción de esta variable sí será visible. Se puede especificar el parámetro
       * para indicar cual será el valor predeterminado.
       * @default myValue*/
      public var myProperty:String;
      
      /**La descripción del constructor*/
      public function CommentedClassExample(){
         this.myProperty="myValue";
      }
      
      /**Ahora podemos poner una descripción de un método.
       * @param parametro1 Descripción del parámetro.
       * @param parametro2 Descripción del parámetro.
       * @return un comentario soble el valor devuelto, que puede ser <code>true</code>
       * @example También podemos poner un ejemplo, con código:
       *   <listing version="3.0" >
       *  var stupidObject:CommentedClassExample=new CommentedClassExample();
       * stupidObject.doSomething("hallo", "world");  </listing>
       * */
       public function doSomething(param1:String,param2:String):Boolean
       {
          trace (param1+" "+param2);
          return Boolean(Math.floor(Math.random()*2));
       }
       
       /** También podemos referenciar a otro método, usando la etiqueta;
       * @see #doSomething()
       * */
       public function doTheSame():Boolean{
          return doSomething("hallo","world");
       }
      
   }
}

y...

Código :

package examples.packagetwo
{
   import examples.packageone.CommentedClassExample;
   
   /**Esta será otra clase de otro paquete.*/
   public class OtherClass
   {
      /**Definimos un método.Si ya hemos definido la clase, se vincula sola cada 
       * vez que aparece (en el valor de return, por ejemplo). También podemos usar el tag &#64see para referenciar
       * a otros paquetes o urls externas.
       * @see examples.packageone.CommentedClassExample
       * @see examples.packageone.CommentedClassExample#doSomething()
       * @see http://www.cristalab.com*/
      public function yoquese():CommentedClassExample{
         return new CommentedClassExample();
      }
   }
}

Una vez que tengamos esto, tenemos que usar el ejecutable de asdoc, pesándole todos los parámetros que necesita. Una manera fácil de hacer esto es crear un archivo .bat (con cualquier editor de texto) dentro de la carpeta en la que tengamos el proyecto de flex. Con la primera línea hacemos que nos lleve a la carpeta donde esté el ejecutable de asdoc, dentro del sdk de flex, que será algo como esto:

Código :

path C:\Archivos de programa\Adobe\Flex Builder 2\Flex SDK 2\bin

En la siguiente línea ejecutaremos el comando, donde el parámetro -source-path es la carpeta donde está nuestro proyecto (como el .bat está allí con un punto [.] bastará), -doc-sources es la carpeta donde tiene que empezar a rastrear código (igual bastará con poner un punto), -output es la carpeta donde se generará el html y -main-title y -window-title son los títulos del header y de la ventana, respectivamente.

Código :

asdoc -source-path . -doc-sources . -main-title "Ejemplo de uso de asdoc" -window-title "Documentando mi Proyecto"  -output ref

Después ponemos un pause para poder leer los errores por si los hay:

Código :

pause
 

Ahora ya podemos ejecutar el comando, y si todo salió bien, podremos ver en la carpeta ref un motón de archivos con in index que mostará nuestras clases.

Si queremos excluir alguna clase, por ejemplo el mxml principal (llamado main.mxml, por ejemplo), podemos añadirle al bat un parámetro -exclude-classes, dejando el código así:

Código :

path C:\Archivos de programa\Adobe\Flex Builder 2\Flex SDK 2\bin
asdoc -source-path . -doc-sources . -main-title "Ejemplo de uso de asdoc" -window-title "Documentando mi Proyecto"  -output source -exclude-classes sendBitmap
pause

Espero que les haya servido.

¿Sabes SQL? ¿No-SQL? Aprende MySQL, PostgreSQL, MongoDB, Redis y más con el Curso Profesional de Bases de Datos que empieza el martes, en vivo.