Pros y contras de versionar javadoc

Me pregunto si debo o no enviar files Javadoc al repository SVN de mi proyecto.

He leído acerca de las buenas prácticas de SVN, incluidas varias preguntas interesantes sobre SO, pero ya no se me ha preguntado ninguna sobre el event handling javadoc.

Al principio estaba de acuerdo con los arguments de que solo el código fuente debe ser versionado, y pensé que javadoc era realmente fácil de volver a comstackr con Eclipse, o desde un file javadoc.xml ant, por ejemplo, pero también pensé en estos puntos:

  • Los files Javadoc son livianos, codificados por text, y los cambios en estos files se pueden rastrear fácilmente con herramientas diff.
  • Parece interesante rastrear fácilmente los cambios en el javadoc, ya que en el caso de un javadoc "público", cualquier cambio probablemente signifique un cambio en el API.
  • Las personas dispuestas a mirar el javadoc no necesariamente quieren get todo el proyecto y comstackrlo, por lo que ponerlo en el repository parece una idea tan buena como otra para permitir un uso compartido / seguimiento eficiente.

¿Cuáles son sus pensamientos sobre esto? Por favor responda con arguments constructivos, no subjetivos. Estoy interesado en comprender qué escenarios de casos fomentan el control de versiones de Javadoc, y que lo hacen parecer una mala elección.

Un argumento en contra sería combinar conflictos, y como antiguo usuario de SVN, odio fusionarme con SVN. Incluso con Git esto es solo un paso más del trabajo si ocurren esos problemas. Y si estás en un equipo más grande, las fusiones regulares son un trabajo diario.

Otro argumento en contra sería, si algunas personas no quieren todo el tree fuente, colocar todo el proyecto bajo algún sistema de CI como Hudson y activar la creación de javadocs de forma regular, como commits y publicarlos en algún lugar.

Conclusio para mí es: no versión javadocs.

Recientemente agregué algunos resultados de javadoc a un sistema de control de versiones (ya que github muestra los contenidos de la twig gh_pages como un website, esta era la forma más fácil de ponerlos en la web ).

Un problema aquí es que javadoc pone en cada file la date / hora de la ejecución de javadoc, por lo que siempre tendrá cambios en todos sus files de una confirmación a la siguiente. Así que no espere poder tener un diff útil que le muestre qué documentation realmente cambió entre sus versiones, siempre y cuando no logre ignorar de alguna manera estas líneas de comentarios cuando se difiera. (En realidad, debido a otra pregunta , descubrí cómo omitir la timestamp).

Y, por supuesto, siempre debería poder regenerar su javadoc a partir de una verificación de las fonts anteriores. Y para las bibliotecas publicadas, publique el javadoc de la versión lanzada con él.

Para las bibliotecas de terceros que está utilizando dentro de su proyecto como files jar (o cualquier otra cosa que no compile), puede ser útil almacenar el javadoc correspondiente a la versión utilizada dentro del tree de código fuente (y, por lo tanto, también tener versiones). ), aunque.

Respuesta corta: no, no versione sus Javadocs.

Los Javadocs se generan a partir de su código, de forma análoga a sus files .class. Si su API cambia y necesita lanzar una nueva versión de los documentos, siempre puede volver a esa revisión (o hacer una nueva comprobación) y generar los JavaDocs desde allí.

Mis dos centavos…

No sé cuántas veces he DESEADO tener disponibles versiones antiguas de Javadocs. Por ejemplo, puedo estar usando una versión anterior de una biblioteca de terceros, pero los documentos API para esa biblioteca se basan en el código actual. Todo muy bien si estás usando el código actual, pero si estás en una versión anterior, los javadocs podrían engañarte sobre cómo usar la class en cuestión.

Esto es probablemente más un problema con las bibliotecas que distribuyes que con tu propio código interno, pero es algo con lo que me he encontrado una y otra vez