[RFC] javadoc: default to not including timestamps

[Jonathan Gibbons]

Mike,

a) it's not easy to change the option in the JDK build -- it's much 
easier to post-process the output
b) -notimestamp is for javadoc only; it does not prevent Corba 
generating timestamps in comments that will appear the JDK API docs.

-- Jon

On 07/24/2014 11:00 AM, Mike Duigou wrote:
> Why not just use the -notimestamp option?
>
> Mike
>
> On Jul 24 2014, at 10:32 , Jonathan Gibbons 
> <jonathan.gibbons at oracle.com <mailto: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 <mailto: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/9fa8cf4e/attachment-0001.html>