A chave para trabalhar com uma grande base de código é não ter que ler toda a base de código para fazer uma alteração. Para permitir que um programador encontre rapidamente o código que ele está procurando, o código deve ser organizado e a organização aparente. Ou seja, cada unidade lógica no código, do executável, da biblioteca, do namespace, até a classe individual, deve ter uma responsabilidade claramente aparente. Eu não apenas documentaria os arquivos de origem, mas também os diretórios em que eles residem.
As anotações do seu programador também fornecem informações sobre decisões de design. Embora isso possa ser uma informação valiosa, eu a separaria da declaração de responsabilidade (para permitir que o leitor escolha se ele quer ler sobre a responsabilidade da classe ou sua justificativa de design) e mova-a o mais próximo da fonte que descreve quanto possível, para maximizar a chance de a documentação ser atualizada quando o código for (a documentação só é útil se pudermos confiar em sua precisão - a documentação desatualizada pode ser pior do que nenhuma!).
Dito isso, a documentação deve permanecer em DRY, ou seja, não repetir informações que poderiam ter sido expressas em código ou já foram descritas em outro lugar (frases como "os estados da documentação" são um sinal de alerta). Em particular, os futuros mantenedores serão apenas proficientes na linguagem de programação do projeto, pois estão em inglês; parafrasear a implementação nos comentários (o que eu vejo com muita frequência quando as pessoas estão orgulhosas de sua documentação) não tem nenhum benefício, e é provável que divergir da implementação, em particular se a documentação não estiver próxima do código que ela descreve.
Finalmente, a estrutura da documentação deve ser padronizada em todo o projeto para que todos possam encontrá-la (é uma confusão real dos documentos do Peter no rastreador de erros, Sue no wiki, Alan no readme e John no código-fonte. ..).