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.