[RFC] javadoc: default to not including timestamps

[Benedikt Morbach]

> > > 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.
I'm mainly arguing that for most use cases, omitting the timestamp wouldn't hurt/would be better.
Doing this upstream in javadoc seemed to be the most future-proof way, as it just flips the default.
And honestly, the current default is suboptimal for both use cases.
The timestamp should either be in the actual output (not in a comment) or not present at all.

> 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.
Yes, but then you need to keep up with changes in the output (however infrequent those might happen).
Also, I'd like to avoid having to do this for every single file format,
because then the total amount of work is quite significant.
Now, I'm writing a tool to compare .rpms and have to special-case javadoc-generated html files,
someone else will do that for .deb files (or already has?) and for any other distro.

> How do you handle jar/zip files?
As far as I know, jar files get repacked with fixed timestamps, not sure about zip files.
But imo it would be nicer if we could just build them like that in the first place,
like we can invoke gzip with '-n' to prevent it from recording timestamps, so maybe I'll
see if I can do something about that