[RFC] javadoc: default to not including timestamps

[Mike Duigou]

Why not just use the -notimestamp option?

Mike

On Jul 24 2014, at 10:32 , Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:

> FWIW, here is a simple script which we use on the Javadoc team to remove timestamps from docs.  Run the script giving a single argument of a directory containing html files to be "un-stamped".
> 
> For JDK API docs, we not only have to strip out the javadoc timestamps; we also have to strip out the timestamps that appear in some of the generated source files.
> 
> --------------------------8<---------------------------------
> #!/bin/sh
> 
> # Remove timestamps from html files generated by javadoc.
> # This includes timestamps generated by javadoc itself,
> # and timestamps propogated from the javadoc comments.
> 
> for file in $(find $1 -name \*.html | xargs -n 1 grep --files-with-matches "Generated by javadoc" ) ; do 
>     sed --in-place \
>     -e 's/\(-- Generated by javadoc \).*\( --\)/\1(removed)\2/' \
>     -e 's/\(<meta name="date" content="\).*\(">\)/\1(removed)\2/' \
>         -e 's/\(Monday\|Tuesday\|Wednesday\|Thursday\|Friday\|Saturday\|Sunday\), [A-Z][a-z]* [0-9][0-9]*, [12][0-9]* [0-9][0-9:]* \(AM\|PM\) PDT/(removed)/' \
>     $file
> done
> -------------------------->8---------------------------------
> 
> 
> FWIW, one issue that has come to light (and which we are working to fix) is that in some situations, the order of entries within some of the generated files is  not deterministic/consistent.
> 
> -- Jon
> 
> 
> 
> On 07/24/2014 09:47 AM, Martin Buchholz wrote:
>> 
>> 
>> 
>> 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/44dc2fd9/attachment.html>