[RFC] javadoc: default to not including timestamps

[Martin Buchholz]

On Mon, Jul 28, 2014 at 1:50 AM, bmorbach <bmorbach at redhat.com> wrote:

> On Fri, 2014-07-25 at 16:02 -0700, Martin Buchholz wrote:
>
> >         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.
> >
> >
> > I disagree.  There's a long tradition of using Show Source for humans
> > or robots to get more metadata about the web page.  Metadata that
> > might not be worth putting visibly on the page itself.  This data is
> > not incredibly valuable, but it is occasionally useful.  The same way
> > that timestamps on files are occasionally useful.  It's only a few
> > release engineers of the world that are annoyed by the reproducibility
> > problem (yes, I am also affected).  So just go and improve your
> > release-diffing tools.
> >
> Maybe a compromise would be to record the timestamp of the file that the
> docs were built from instead of the current time? That would be useful
> and easily reproducible.
>

I have the feeling that would be a half-way solution that would in the end
not make anyone happy.  Your builds would still not be reproducible because
some java source files are generated.  And the contents of multiple input
files determine the content of a single javadoc output .html file, so
including only one source file timestamp in the output would be slightly
misleading - it might include content added to the sources after the given
date!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20140728/3644fe65/attachment.html>