O ASDoc é uma ferramenta da Adobe que faz com ActionScript o que o JavaDoc faz com o Java: criar documentação HTML de uma API baseado nas próprias classes que compõe essa API e em comentários em um formato padrão presentes nas mesmas.
O próprio Adobe Flex 2 Language Reference foi criado utilizando o ASDoc. Assim fica evidente como é vantajoso ter esse tipo de documentação para uma API. Uma biblioteca de componentes, por exemplo, pode ser facilmente navegável e entendida com uma documentação com esse estilo, que também pode conter exemplos compilados.
O ASDoc contudo ainda não é integrado nativamente ao Flex Builder, mas como ele é um executável de linha de comando, é fácil integra-lo com o Ant. O Ant é um plugin para o Eclipse (mas é tão utilizado que até vêm na instalação deste - mas não vem se você instalou o Flex Builder standalone) e é um utilitário para automatizar tarefas relacionadas com o desenvolvimento, como por exemplo, compilar classes Java, gerar um arquivo para deploy, realizar testes unitários, fazer FTP, etc etc, e claro, executar outros softwares, como o próprio ASDoc. A sintaxe é em XML, o que torna uma ferramenta fácil de utilizar. Há muitas referências sobre o Ant na Internet.
A instalação do ASDoc é simples, basta extrair o conteúdo do arquivo para a pasta onde está localizado o seu SDK. O ASDoc já está pronto para ser utilizado, manualmente, via linha de comando. Mas certamente há outras coisas mais importantes em um projeto para fazermos do que rodar manualmente uma ferramenta como essa. Seria o mesmo que compilar manualmente via linha de comando. É o tipo de tarefa que precisa ser automatizada. E com o Ant, além da documentação que pode ser gerada de dentro do próprio Eclipse, pode se integrar com outras tarefas, como por exemplo, só gerar se passar nos testes unitários, compactar em zip, etc.
Veja um Ant simples para automatizar:
XML:
-
<project name="asdoc" default="create" basedir=".">
-
<property name="asdocExec" location="C:\Program Files\Adobe\Flex Builder 2 Plug-in\Flex SDK 2\bin\asdoc.exe" />
-
<property name="sourcePath" location="${basedir}/. "/>
-
<property name="outputPath" location="${basedir}/docs" />
-
-
<target name="create">
-
<exec executable="${asdocExec}">
-
<arg line="-doc-sources ${sourcePath}" />
-
<arg line="-output ${outputPath}" />
-
</exec>
-
</target>
-
</project>
A primeira propriedade é o local do executável do ASDoc. A segunda é o local onde estão as nossas classes e a terceira onde a documentação deve ser gerada. A proriedade "basedir" é do próprio Ant e está definida na primeira linha, na tag project. E depois vem efetivamente a tarefa, que roda o ASDoc passando os parâmetros mínimos para rodar com sucesso.
No exemplo acima, para o parâmetro -doc-sources é passado um diretório com as nossas classes, e ele percorrerá recursivamente este diretório para gerar a documentação.
Importante: O ASDoc visualiza a existência de arquivos MXML e os adiciona na documentação, mas não os lê para pegar seus comentários internos.
Uma outra possibilidade é utilizar o atributo -doc-classes, que são as classes que queremos documentar. E o ASDoc aqui faz uma coisa muito interessante: ele documenta também as classes que essa classe utiliza. Portanto, se colocarmos o arquivo principal de nossa aplicação, todas as classes utilizadas por ela serão documentadas também. O local em que o ASDoc procura pelas classes devem estar definidos no argumento -source-path. Por exemplo:
XML:
-
<target name="create">
-
<exec executable="${asdocExec}">
-
<arg line="-doc-classes Main" />
-
<arg line="-source-path ." />
-
<arg line="-output ${outputPath}" />
-
</exec>
-
</target>
Ou ainda, caso o seu projeto faça referências a outros, você pode utilizar mais de um source-path. E essa é uma situação comum. Normalmente colocamos o Cairngorm em um projeto separado, a biblioteca de componentes em outro, etc etc. Exemplo:
XML:
-
<arg line="-source-path '..\Cairngorm21' ." />
Há outros parâmetros disponíveis e podem ser utilizadas para customizar a documentação, como o -main-title, para alterar o título do documento, por exemplo. Abaixo um Ant de um projeto aqui da DClick:
XML:
-
<?xml version="1.0" encoding="UTF-8"?>
-
<project name="asdoc" default="_generate" basedir=".">
-
-
<property name="asdocExec" location="C:\Program Files\Adobe\Flex Builder 2 Plug-in\Flex SDK 2\bin\asdoc.exe" />
-
<property name="outputPath" location="${basedir}/docs" />
-
-
<property name="additionalPaths" value="'..\DClickComponents' '..\Cairngorm21'" />
-
<property name="mainClass" value="Main" />
-
-
<property name="docsTitle" value="Projeto - API Documentation" />
-
<property name="docsFooter" value="Copyright 2006 DClick Desenvolvimento de Software Ltda." />
-
-
<target name="_generate" depends="delete,create,open"/>
-
-
<target name="delete">
-
<delete dir="${outputPath}" includeEmptyDirs="true"/>
-
<mkdir dir="${outputPath}" />
-
</target>
-
-
<target name="create">
-
<exec executable="${asdocExec}" failonerror="true">
-
<arg line="-main-title '${docsTitle}'" />
-
<arg line="-window-title '${docsTitle}'" />
-
<arg line="-footer '${docsFooter}'" />
-
-
<arg line="-doc-classes ${mainClass}" />
-
-
<arg line="-source-path ${additionalPaths} ." />
-
<arg line="-output ${outputPath}" />
-
</exec>
-
</target>
-
-
<target name="open">
-
<exec executable="cmd">
-
<arg line="/c" />
-
<arg line="${outputPath}\index.html" />
-
</exec>
-
</target>
-
-
</project>
Normalmente rodamos a tarefa "_generate", que dispara as demais tarefas: a primeira (delete) para limpar o diretório e assim remover arquivos não mais utilizados, a segunda (create) que efetivamente chama o ASDoc, e a terceira (open) que abre o arquivo principal da documentação na máquina do desenvolvedor.
Notem os argumento de customização (main-title, window-title, footer), a classe principal (Main, que na verdade é o Main.mxml, presente na raiz), e os paths adicionais em source-paths (do projeto DClickComponents e do projeto Cairngorm21).
O ASDoc é uma boa ferramenta e certamente irá evoluir, como dar suporte para geração de comentários a partir de MXML (não muito útil para telas, mas de extrema importância para componentes) e possivelmente uma maior integração com o Flex Builder. O Ant certamente nos facilita um bocado com automatização e assim podemos utilizar o nosso tempo para atividades mais importantes. O conceito e a ferramenta também podem ser utilizados para compilar arquivos do Flex com o SDK, sem a necessidade do Flex Builder (mas ainda utilizando o Eclipse como IDE).
