Pros and cons of javadoc version

Question

I am wondering if I should transfer Javadoc files to my SVN project repository.

I read about good SVN practices, including some interesting questions about SO, but no one was asked specifically to handle javadoc.

At first I agreed with the arguments that only the source code should be a version, and I thought that javadoc was really easy to rebuild using an Eclipse or from javadoc.xml ant file example, but I also thought about these points:

• Javadoc files are lightweight, text, and changes to these files are easily tracked using diff tools.
• It seems interesting to easily track changes in javadoc, since in the case of a "public" javadoc, any change to it would probably mean a change to the API.
• People who want to look at javadoc do not necessarily want to get the whole project and compile it, so including it in a repo seems like a good idea like another to provide an efficient exchange / tracking.

What do you think about this? Please respond to constructive, non-subjective arguments. I am interested in understanding which behavioral patterns encourage the execution of Javadoc, and what makes it seem like a bad choice.

Answer 1

One argument against this is merge conflicts, and as a former SVN user, I hate merging with SVN. Even with Git, this is another work step if these problems arise. And if your regular team in the larger team has regular mergers, this is daily work.

Another argument will be that if some people don’t want to get the whole source tree, put the whole project under some CI system like Hudson and run javadocs on a regular basis, for example, make and publish them somewhere.

Conclusio for me is not a javadocs version.

Answer 2

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

One of the problems is that javadoc puts javadoc launch date / time on each file, so you always have changes to all your files from one commit to the next. Therefore, do not expect that you will have a useful diff that will show you what documentation has really changed between your versions if you fail to somehow ignore these comment lines when distinguishing. (Actually, due to another question, I figured out how to skip the timestamp.)

And, of course, you can always restore your javadoc from checking old sources. And for released libraries, publish javadoc of the released version with it.

For third-party libraries that you use as jar files in your project (or anything you don’t compile yourself), it may be useful to keep the javadoc corresponding to the version used inside the source tree (and therefore the version too).

Answer 3

Short answer: no, do not use your Javadocs.

Javadocs are generated from your code, similar to your .class files. If your API changes and you need to release a new version of documents, you can always go back to this revision (or perform a new check) and create Javadocs there.

Answer 4

My two cents ...

I do not know how many times I WISHED, I had old versions of Javadocs. For example, I can use an old version of a third-party library, but the API documents for this library are based on the current code. All is well and good if you use the current code, but if you use an older version, javadocs may actually mislead you about using the class in question.

This is probably more of a problem with the libraries you distribute than with your own internal code, but this is what I came across again and again