« Add Nothing But Value | Main | If you can't type them, join them »

Why do people check Javadocs into version control?

Every now and again you run into an open source project that has its Javadoc checked into source control. Why fill your source tree with html when it can be generated on demand from source?


August 16, 2004 09:18 PM

Comments

Lasse
(August 16, 2004 10:07 PM #)

By accident?

Henri Yandell
(August 17, 2004 03:45 AM #)

Possibly as a way to deploy them.

It saves on the user's on the machine a lot.

Jason Yip
(August 17, 2004 04:09 AM #)

Henri,

But you don't need to check in to source control. Just add a dependency to the release target that generates javadoc. If you mean so that developers don't need to generate javadoc locally, I'm wondering what kind of IDE they're using...

Craig McClanahan
(August 17, 2004 04:44 AM #)

It is easy to generate Javadocs for the *current* version of the sources, using the supplied Ant build.xml file (or whatever). It is not necessarily so easy to generate Javadocs for historically released versions that might actually still be in production application use. That's why, on Struts, we check in "legacy" Javadocs as a convenience to our users who would otherwise have to learn how to check out a branch of CVS in order to generate the Javadocs for the version they are actually using in production right now.

Ross Mason
(August 17, 2004 05:42 AM #)

Isn't it better to include the javadocs in the full distribution of your project, rather than clutter up cvs with auto-generated files? If people need legacy javadoc they can get it from the original distribution.

Craig McClanahan
(August 17, 2004 06:27 AM #)

> Isn't it better to include the javadocs in the
> full distribution of your project, rather than
> clutter up cvs with auto-generated files? If
> people need legacy javadoc they can get it
> from the original distribution.

Of course including the javadocs in the original distribution is a good idea, and we do that too. But that doesn't help the fact that the Struts web site content is generated, and we want to include links for the legacy versions that Struts users actually have deployed ***in addition to*** the Javadocs for the latest and greatest development version (which is, indeed, generated from the CVS sources).

Craig

Bill de hra
(August 17, 2004 09:29 AM #)

"It is not necessarily so easy to generate Javadocs for historically released versions that might actually still be in production application use."

Craig, can someone not checkout the historic version and build the docs from that?

Robert 'Groby' Blum
(August 18, 2004 03:46 PM #)

Ah, the age-old debate of checking in generated data or not.

I can't speak for the JavaDoc crowd - maybe that tool is unbearably fast - but doxygen (the poison of choice for us, since we use C++) takes quite a bit of time when you run it on a large project.

I'd rather look at the docs as soon as I got the source, without having to wait 10 minutes until the HTML is finally generated.

Then again, I also like compiled libraries to be part of the revision control system. Storage is cheap, my time is not.

Trackback Pings

TrackBack URL for this entry:
http://www.dehora.net/mt/mt-tb.cgi/1389