Em termos de funcionalidade, o gerador de documentação que mais entrega o que se espera é o famoso JSDoc, que é basicamente uma cópia do Javadoc.
Entretanto, ele apresenta 2 problemas fundamentais: dificuldade de se customizar a documentação e poluição severa do código-fonte com comentários.
/**
* Valida um movimento de xadrez.
*
* @param aColunaDe Coluna atual da peça a ser movida
* @param aLinhaDe Linha atual da peça a ser movida
* @param aColunaPara Coluna destino da peça a ser movida
* @param aLinhaPara Linha destino da peça a ser movida
* @return verdadeiro se o movimento é válido ou falso se inválido
* @author Joana Silva
* @author Nuno Martins
*/
boolean validaMovimento(int aColunaDe, int aLinhaDe, int aColunaPara, int aLinhaPara)
{
...
}O código-fonte pode até dobrar de tamanho devido a esses comentários. Quanto mais bem estruturada a documentação (com parágrafos, quebras de linha etc), mais longo resulta o código-fonte, desmotivando a elaboração de documentações bem feitas.
Além disso, não se pode utilizar itálico, negrito, tabelas etc, que são elementos simples que contribuem muito para a clareza da documentação. Seria desejável que houvesse suporte a Markdown, mas isso acarretaria uma poluição ainda maior do código-fonte, além do que tudo tem de ser escrito na forma de comentários.
Projetar um gerador de documentação baseado na integração entre Markdown e AST com o intuito de não ser mais necessário escrever comentários no código-fonte e com a possibilidade de se estilizar tudo com Markdown.
O dev poderia escrever a documentação dentro do próprio arquivo AST gerado. No entanto esse AST não pode ser completo: um import numa única lib de terceiros já geraria um AST gigantesco e inviável de se manter. Talvez possam ser usados comentários vazios (/** */) para indicar o que deve ser exportado para o AST.