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 < (<) o @(@ , 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:
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 > 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");
}
}
}
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 @see 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();
}
}
}
Código :
path C:\Archivos de programa\Adobe\Flex Builder 2\Flex SDK 2\bin
Código :
asdoc -source-path . -doc-sources . -main-title "Ejemplo de uso de asdoc" -window-title "Documentando mi Proyecto" -output ref
Código :
pause
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
