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

8

¿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.

java documentation javadocs Dakota del Sur
fuente
¿Por qué necesitarías esto?
mosquito
1
@downvotes parece que he irritado a los codificadores religiosos :)
SD
2
Por favor, ilumíneme sobre lo que en esta pregunta lo hace poco práctico, irreal. Yo también lo apreciaré.
SD
44
Sería genial si su pregunta explicara qué tipo de problemas tiene con el javadoc estándar. Tal como está redactado actualmente, es difícil saber si hay algún problema, por lo que intentar responder a la pregunta es un juego de adivinanzas
mosquito el
3
El verdadero problema con documentar el código en un archivo diferente es que es menos probable que se actualice. Cuando una función cambia, a veces la documentación no siempre se actualiza para que coincida exactamente. Si la documentación se mueve a un archivo diferente, ahora hay un paso adicional para realizar el cambio correcto. También hace que sea menos obvio que la documentación es incorrecta. Solo lo verá cuando mire específicamente la documentación, no cuando lo pase en el código.
unholysampler

Respuestas:

8

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.

mosquito
fuente
¿Cómo encuentra package-info.java desde la perspectiva de escribir realmente el texto, las etiquetas HTML, las palabras clave de javadoc, etc.? ¿Es torpe o no es un problema?
Adam