@ USP

Há quem pense que documentar um programa é o mesmo que escrever muitos comentários de mistura com o código. Totalmente errado! Uma boa documentação não suja o código com comentários. Uma boa documentação limita-se a

explicar o que cada função do programa faz.

Em geral, uma boa documentação não perde tempo tentando explicar como uma função faz o que faz, porque o leitor interessado nesse assunto é capaz de ler o código.

Sucinto como deve ser.
Digo até mais: a documentação deve seguir a premissa de ser simplória e clara, e não toneladas de caracteres que tentam te informar como a execução da função retorna (quando retorna) algo.