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