Uau, isso é realmente muito legal! Automatizar a documentação com IA é definitivamente um tema quente no momento, e dá para entender o porquê, é uma economia de tempo enorme e parece tirar muita da chatice dessa tarefa. Agora em uma pesquisa rápida, encontrei dezenas artigos acadêmicos publicados em 2023 ou 2024 que abordam exatamente essa questão. Então, parabéns por criar algo tão relevante e atual!

No entanto, embora automatizar o processo de documentação pareça um sonho se tornando realidade, há alguns pontos importantes que me deixam muito receoso.

1. Escrever documentação não se trata apenas de descrever o que o código faz, é uma oportunidade de entender profundamente a base de código, refletir sobre as decisões de design e garantir que tudo faz sentido. Quando você automatiza isso, perde uma etapa crucial de compreensão do código e de garantia de qualidade. Será que nessa 20 horas que supostamente "economizou", na verdade não perdeu a chance de encontrar alguma problema grave do software antes de realizar a entrega ao cliente?
2. Boa documentação vai muito além de uma simples descrição do código. Ela deve cobrir o porquê das decisões, explicar o processo de pensamento e destacar justamente os aspectos que não óbvios através do código. Nenhum script, por mais avançado que seja, vai ser capaz de captar a intenção ou o raciocínio por trás de decisões não triviais.
3. Há o risco de a IA gerar uma documentação que seja enganosa ou até completamente errada, o que é pior do que não ter documentação nenhuma.

Então, embora automatizar a documentação seja uma ideia empolgante e promissora, eu recomendaria usar isso com muito cautela. Pode ser um ótimo complemento, especialmente para tarefas de documentação repetitivas ou diretas, mas para bases de código onde a qualidade da documentação realmente importa, nada supera a comprensão adquirida ao revisar e documentar manualmente o seu código.

De forma alguma estou desencorajando o trabalho do jeffz, muito pelo contrário! Iniciativas como essa são exatamente o tipo de inovação que buscamos. Estou apenas apontando alguns aspectos que acredito serem importantes para pensar a respeito. A automação é ser uma ferramenta poderosa para otimizar processos e economizar tempo. Eu acredito fortemente que a IA generativa será a base para a próxima geração de ferramentas CASE, que serão ainda mais disruptivas do que as dos anos 90.

Documentação e rastreamento de artefatos de design e testes vinculados ao código-fonte, vinculação bidirecional de representações AST do código e da documentação, analisadas por IA. Em suma, penso que a automação da documentação por ferramentas de IA vai transformar muito positivamente a forma como desenvolvemos software, se for utilizada em um complemento à expertise humana, em um processo colaborativo, não em sua substituição.

Ao invés de querer ver o código como os outros, mas gostaria de ver um artigo que detalhasse os resultados obtidos com a sua ferramenta, em termos de precisão e qualidade por exemplo. Além disso, o que eu realmente quero saber é como integrar o humano no processo, em vez de delegar completamente à máquina. Acredito que o futuro da documentação está na integração de sugestões automáticas ao estilo LSP (Language Server Protocol), já pensou algo sobre?

Um abraço e bons estudos!