A documentação do código Java em um arquivo docs separado, de alguma forma, mapeada para um arquivo de origem?

Qual seria uma boa alternativa para a documentação Java embutida, ou seja, é possível ter um arquivo de documentos separado de alguma forma mapeado para um arquivo de origem java?

Eu nunca gostei de grandes seções de comentários repletas de código.

Eu tenho usado o recurso Javadoc dos comentários do pacote para evitar desarrumar o código-fonte com comentários detalhados da documentação:

Comentários em nível de pacote

Com o Javadoc 1.2, os comentários dos documentos no nível do pacote estão disponíveis. Cada pacote pode ter seu próprio arquivo de origem de comentários de documento no nível do pacote que A ferramenta Javadoc irá mesclar na documentação que produz. Este arquivo é nomeado package.html(e é o mesmo nome para todos os pacotes). Este arquivo é mantido no diretório de origem junto com todos os *.javaarquivos. (Não coloque o packages.htmlarquivo no novo diretório de origem dos arquivos doc, porque esses arquivos são copiados apenas para o destino e não são processados.)

O arquivo package.html é um exemplo de arquivo de origem no nível do pacotejava.text e package-summary.html é o arquivo que a ferramenta Javadoc gera.

A ferramenta Javadoc processa package.htmlfazendo três coisas ...

Usando o recurso acima, eu tinha documentação detalhada detalhada para classes e métodos no pacote armazenado separadamente do código, em um arquivo html dedicado. Quanto aos comentários do Javadoc nos arquivos java, acabei de escrever breves explicações, adicionando texto como

Se necessário, consulte a documentação do pacote para obter mais detalhes.

Uma coisa que eu particularmente gostei disso foi que, embora os documentos estivessem em um arquivo separado e em um formato mais conveniente para documentos grandes (html), ele foi armazenado perto o suficiente do código-fonte relacionado e todas as atualizações nele foram coletadas automaticamente durante a compilação.

A partir do Java 1.5 , você pode alternativamente colocar package-info.javajunto com as classes do pacote. Este arquivo deve ficar assim:

/**
 * Javadoc for your package here
 */
package com.yourpackage;

A documentação do JLS sugere que esta é a maneira preferida:

O esquema a seguir é altamente recomendado para implementações baseadas no sistema de arquivos: A única declaração de pacote anotado, se existir, é colocada em um arquivo de origem chamado package-info.javano diretório que contém os arquivos de origem do pacote ...

Recomenda-se que package-info.java, se houver, substitua o package.htmljavadoc e outros sistemas de geração de documentação semelhantes. Se esse arquivo estiver presente, a ferramenta de geração de documentação deve procurar o comentário da documentação do pacote imediatamente antes da declaração do pacote (possivelmente anotada) no package-info.java. Dessa forma, package-info.javatorna-se o único repositório para anotações e documentação em nível de pacote. Se, no futuro, tornar-se desejável adicionar outras informações no nível do pacote, esse arquivo deve ser um local conveniente para essas informações.