Pros and cons of versioning javadoc

Question

I am wondering whether or not to commit Javadoc files to my project's SVN repository.

I have read about SVN good practices, including several interesting questions on SO, but none has already been asked specifically on javadoc handling.

At first I was agreeing with the arguments that only source code should be versioned, and I thought that javadoc was really easy do re-build with Eclipse, or from a javadoc.xml ant file for example, but I also thought of these points :

• Javadoc files are light, text-encoded, and changes to these files are easily trackable with diff tools.
• It seems interesting to easily track changes to the javadoc, since in the case of a "public" javadoc, any change of it would probably mean a change in the API.
• People willing to look at the javadoc do not necessarily want to get the whole project and compile it, so putting it in the repo seems as good an idea as another to allow for efficient sharing/tracking.

What are your thoughts about this? Please answer with constructive, non-subjective arguments. I am interested in understanding which case scenarios encourage the versioning of Javadoc, and which make it seem a bad choice.

Answer 1

One argument against would be merge conflicts, and as a former SVN user I hate merging with SVN. Even with Git this is just another step of work to do if those problems occur. And if your in a bigger team regular merges are daily work.

Another argument against would be, if a some people don't want the whole source tree, put the whole project under some CI system like Hudson and trigger the creation of the javadocs on a regular basis, like commits and publish them somewhere.

Conclusio for me is: don't version javadocs.

Answer 2

I recently added some javadoc output to a version control system (since github shows the contents of branch gh_pages as a website, this was the easiest way to put them on the web).

One problem here is that javadoc puts in every file the date/time of the javadoc run, so you always have changes to all your files from one commit to the next. So don't expect to be able to have a useful diff which shows you what documentation really changed between your versions, as long as you don't manage to somehow ignore these comment lines when diffing. (Actually, due to another question I found out how to omit the timestamp.)

And of course, you should always be able to regenerate your javadoc from a checkout of the old sources. And for released libraries, publish the javadoc of the released version with it.

For third party-libraries which you are using inside your project as jar files (or anything that you don't compile yourself) it might be useful to store the javadoc corresponding to the version used inside the source tree (and thus be versioned, too), though. (When using Maven, you usually can download a javadoc jar together with the runnable jar of the library, so then it doesn't apply.)

Answer 3

Short answer: no, don't version your Javadocs.

The Javadocs are generated from your code, analogous to your .class files. If your API changes and you need to release a new version of the docs, you can always revert to that revision (or do a new check out) and generate the Javadocs from there.

Answer 4

My two cents...

I don't know how many times I've WISHED I had old versions of Javadocs available. For example, I may be using an old version of a third-party library, but the API docs for that library are based on the current code. All well and good if you're using the current code, but if you're on an older version, the javadocs could actually mislead you on how to use the class in question.

This is probably more of an issue with libraries you distribute than with your own internal code, but it is something I've run into now and again