Você já pensou em documentar seus scripts dentro deles mesmos em um formato padrão e ainda poder utilizar essa documentação no seu editor, contando até com auto-completar? Se você usa o Aptana, o ScriptDoc lhe provê esses recursos.

O Code Assist

Ferramentas que facilitam a vida do desenvolvedor não faltam no Aptana. O Code Assist é uma delas. Quando você digita o nome de algum objeto (document, por exemplo), ele mostra todos os métodos e propriedades disponíveis, permitindo que você complete o código sem precisar digitá-lo por inteiro. Isso também funciona para funções comuns, quando se começa a digitar seu nome.

Além de completar seu código, o Code Assist ainda mostra as informações sobre o método, como parâmetros, retorno, descrição e compatibilidade (no caso de métodos do JavaScript ou DOM) através de uma tooltip. Essa mesma tooltip também aparece quando se digitam os parênteses de alguma função, mostrando seus parâmetros e suas descrições.

Também é possível usar o Code Assist com seus próprios scripts, ou seja, usar toda essa facilidade juntamente com as classes, métodos e funções que você escreveu. Para usar o Code Assist com seus códigos, é necessário documentá-los através do ScriptDoc, mais uma ferramenta do Aptana.

O ScriptDoc

A documentação através do ScriptDoc funciona com blocos de comentário dentro do próprio código JavaScript, seguindo um padrão definido. Basicamente, um bloco de documentação deve ser assim:

/**
* Descrição do Código
*/

Esse bloco deve ser incluído logo acima da função que se deseja documentar, e ela será automaticamente vinculada à esse bloco de documentação pelo parser do Aptana. A primeira linha, para todos os blocos de documentação (exceto na descrição de arquivos), deve ser uma pequena descrição da classe, método ou atributo. Nas linhas seguintes podem ser incluídas tags que adicionem mais informações sobre o código.

/**
* Cria um elemento HTML
* @param {String} tagName Nome da tag a ser criada
* @return {Object} Retorna a tag criada
*/
function createHTMLElement(tagName) { }

O ScriptDoc permite várias tags, as duas usadas acima são apenas para um exemplo simples. Há uma lista compreensiva de tags na documentação do Aptana, tanto on-line quanto off-line. Veja o resultado da função documentada:

A descrição de arquivos também pode ser feita de maneira bem semelhante, através da tag @projectDescription, e outras que também podem ser usadas no restante da documentação.

/**
* @projectDescription Descrição do Arquivo
* @author Autor
* @version 1.0
*/

Usando arquivos .sdoc

Caso você não queira que sua documentação fique diretamente no script, apenas ocupando espaço desnecessário, ela pode ser colocada em um arquivo externo, de extensão .sdoc.

Para que esse tipo de documentação funcione, é necessário criar um arquivo com o mesmo nome do script, mas com a extensão .sdoc, fazendo com que o Aptana reconheça o arquivo como sendo documentação do script.

No arquivo .sdoc, pode-se escrever a documentação normalmente, assim como seria no script. Há apenas uma modificação a ser feita: deve ser incluída a tag @id para cada bloco de documentação, e deverá haver uma tag correspondente no script (somente a tag @id). Veja um exemplo do arquivo .sdoc:

/**
* Cria um elemento HTML
* @id createHTMLElement
* @param {String} tagName Nome da tag a ser criada
* @return {Object} Retorna a tag criada
*/

E também um exemplo do script:

/**
 * @id createHTMLElement
 */
function createHTMLElement(tagName) { }

No início de ambos os arquivos também pode ser inclusa a tag @namespace, que definirá um objeto que englobará todas as funções e atributos do script. Se incluíssemos @namespace HTML em nossos exemplos, poderíamos usar tanto createHTMLElement quanto HTML.createElement. É claro que não funcionaria no script, a menos que assim quiséssemos.

É por isso que a cada dia mais gosto do Aptana, apesar de ser extremamente pesado (Aptana + WMP não dá certo). Adicionando mais tags pode-se criar uma documentação ótima para seus scripts, e de uma maneira muito simples. Também há planos de um gerador HTML para a documentação ScriptDoc, basta esperar. Pra quem não conhece o Aptana, vale o teste. Aproveitem, e até a próxima!