¿Documentación de código Java en un archivo de documentación separado de alguna manera asignado a un archivo fuente?

¿Cuál sería una buena alternativa a la documentación en línea de Java, es decir, puede uno tener un archivo de documentos separado de alguna manera asignado a un archivo fuente de Java?

Nunca me han gustado las grandes secciones de comentarios llenas de código.

He estado utilizando la función Javadoc de los comentarios del paquete para evitar ensuciar el código fuente con comentarios detallados de la documentación:

Comentarios a nivel de paquete

Con Javadoc 1.2, los comentarios de documentos a nivel de paquete están disponibles. Cada paquete puede tener su propio archivo fuente de comentarios de documentos a nivel de paquete que la herramienta Javadoc combinará en la documentación que produce. Este archivo se llama package.html(y es el mismo nombre para todos los paquetes). Este archivo se mantiene en el directorio fuente junto con todos los *.javaarchivos. (No coloque el packages.htmlarchivo en el nuevo directorio fuente de doc-files, porque esos archivos solo se copian en el destino y no se procesan).

El archivo package.html es un ejemplo de un archivo fuente a nivel de paquetejava.text y package-summary.html es el archivo que genera la herramienta Javadoc.

La herramienta Javadoc procesa package.htmlhaciendo tres cosas ...

Usando la función anterior, tenía documentación detallada detallada para clases y métodos en el paquete almacenado por separado del código, en un archivo html dedicado. En cuanto a los comentarios Javadoc en archivos java, acabo de escribir breves explicaciones allí, agregando texto como

Si es necesario, consulte la documentación del paquete para obtener más detalles.

Una cosa que me gustó especialmente de esto fue que, aunque los documentos estaban en un archivo separado y en un formato más conveniente para documentos grandes (html), se ha almacenado lo suficientemente cerca del código fuente relacionado y todas las actualizaciones en él se recogieron automáticamente durante La construcción.

A partir de Java 1.5 , también puede poner un package-info.javajunto con las clases del paquete. Este archivo debería verse así:

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

La documentación de JLS sugiere que esta es la forma preferida:

El siguiente esquema se recomienda encarecidamente para las implementaciones basadas en el sistema de archivos: la única declaración de paquete anotada, si existe, se coloca en un archivo fuente llamado package-info.javaen el directorio que contiene los archivos fuente para el paquete ...

Se recomienda que package-info.java, si está presente, tome el lugar de package.htmljavadoc y otros sistemas de generación de documentación similares. Si este archivo está presente, la herramienta de generación de documentación debe buscar el comentario de la documentación del paquete inmediatamente anterior a la declaración del paquete (posiblemente anotada) en package-info.java. De esta forma, se package-info.javaconvierte en el único repositorio de anotaciones y documentación a nivel de paquete. Si, en el futuro, resulta deseable agregar cualquier otra información a nivel de paquete, este archivo debería ser un hogar conveniente para esta información.