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:

Exemplo da documentação gerada:

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