Summary

Support a new --date option to specify the timestamp to use for the timestamps in generated files.

Problem

It is useful and even good practice to support reproducible builds. While otherwise useful, embedding timestamps in generated files can be a problem in that regard.

Solution

Up to now, javadoc has just supported the -notimestamp option which totally suppresses any timestamps. A better solution is to allow the timestamp to be specified, using a new --date option. This is similar to the use of the --date option for the jar and jmod tools.

Specification

The --date option is a new "extended option" that takes an argument in ISO 8601 format. The value must be within ten years of the time of use. It is an error to specify both --date ... and -notimestamp.

The format of the timestamps in the generated files is unchanged. In particular, it should not be assumed that the timestamps in the generated files will be String.equals to the value of the --date option.

The command-line help shows:

--date <date-and-time>
  Specifies the value to be used to timestamp the generated
  pages, in ISO 8601 format