fgrillo.net Blog do grillo

16Mar/080

Documentando arquivos JavaScript

Para documentar arquivos JavaScript, uma excelente opção é utilizar o JSDoc (link), já utilizei ele na versão 1.9.9.2 para a primeira versão de minha ferramenta WebDia e agora pretendo utilizar a nova versão (1.10.2) para documentar a versão refatorada da ferramenta pois ela será escrita com paradigma de orientação a objetos.

Para quem não conhece, o JSDoc é uma ferramenta escrita em Perl que gera páginas de documentação a partir de tags nos comentários internos dos arquivos javascript. Seu uso na documentação é extremamente semelhante ao JavaDoc da linguagem Java e o resultado é também muito parecido!

O único probleminha com ela é que não é tão trivial de instalar, é preciso ter Perl e algumas outras dependências, mas tudo é muito bem explicado no site do JSDoc, vale a pena conferir! Veja abaixo um exemplo do código da WebDia e um screenshot da documentação gerada pelo JSDoc.

Exemplo de código comentado com tags do WebDia:

código da ferramenta WebDia

Exemplo da documentação gerada:

código da ferramenta WebDia

Documentação é uma das partes mais importantes de um software! quem nunca pegou um próprio código depois de algums meses e perdeu boas horas de trabalho tentando entender como ele funciona? O ideal seria registrar todas as experiências e decisões que tomamos em relação ao projeto de software. Chamam-se esses registros de Design Rationale do software e existem ferramentas que ajudam na captura e manutenção desses documentos. Mas isso fica para um próximo post!

Filipe Grillo

Post to Twitter Post to Delicious Post to Digg Post to Facebook