[RFC] javadoc: default to not including timestamps

[Martin Buchholz]

On Thu, Jul 24, 2014 at 8:28 AM, Benedikt Morbach <bmorbach at redhat.com>
wrote:

> > At Google we also strive for repeatable builds.  We find timestamps
> > embedded in jar files to be the biggest problem.
> >
> > Timestamps are useful for users checking up-to-dateness via the "Show
> > Source" action in a web browser.
> Isn't it more useful to just have the version that the docs were built for
> displayed?
> That would be easier to find than having to look at comments in the html
> source and
> "These are the docs for version 1.2" seems more useful than "these docs
> were built on 2014/07/01"
>
>
It depends.  My own most-read javadoc is
http://gee.cs.oswego.edu/dl/jsr166/dist/docs/java/util/concurrent/CompletableFuture.html
and that has no release version associated with it.  The value of the
timestamps may be small, but it is definitely non-zero.

It depends on the use case.  For Linux operating system deployments, it
makes a lot of sense to drop the timestamp, especially because the user
will have a good chance of being able to observe the timestamps of the
underlying files.

But I think the Right Thing to do is to add the extra tooling to compare
javadoc-generated html files and ignore the timestamp differences, and that
should be less total work than persuading all the javadoc generating tools
not to produce them.

How do you handle jar/zip files?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20140724/60952bdc/attachment.html>