Javadoc para la documentación del proyecto

Question

Quiero documentar un proyecto Java en el que estoy trabajando. En el pasado, normalmente documenté el diseño y la API de software en una wiki. Sin embargo, después de usar Mockito recientemente para pruebas de burla, quedé impresionado con la cantidad y calidad de la documentación a nivel de proyecto en los javadocs reales.

Mi pregunta es, ¿la gente suele usar Javadocs para documentar la vista de nivel superior del proyecto (por ejemplo, arquitectura, decisiones de diseño, etc.) o este tipo de información está mejor documentada en (digamos) una wiki?

Answer 1

Depende de quién sea su público.

Si su público va a utilizar principalmente la API, generalmente es mejor invertir en descripciones claras y concisas (con ejemplos) en su Javadoc. Si es probable que el público nunca vea la API, entonces es mejor mantener su documentación fuera de Javadoc. Esta es una función primaria de cómo se navega la documentación; La navegación Javadoc facilita el proceso de programación.

En cuanto a si desea colocar la documentación en una wiki o en un PDF, de nuevo depende de la audiencia. Si la única razón para wiki es tener una representación HTML de la documentación frente a la web, el uso de algo similar a Docbook podría proporcionar dicha documentación con el beneficio adicional de la capacidad de generar representaciones en PDF de la misma documentación. Si realmente tienes una comunidad activa, wiki brilla por la capacidad de permitir que casi desconocidos modifiquen tu documentación.

Determine si los puntos fuertes de los productos se ajustan a sus necesidades, y si lo hacen, entonces es la elección correcta.

Answer 2

Javadoc es ideal para generar documentación de nivel de API. Uso una wiki para mi documentación de alto nivel. Uso confluence como mi wiki y hay algunos complementos que puede usar para diagramas arquitectónicos.