[RFC] javadoc: default to not including timestamps
bmorbach at redhat.com
bmorbach at redhat.com
Wed Jul 23 14:56:06 UTC 2014
From: Benedikt Morbach <bmorbach at redhat.com>
having those timestamps in there generally isn't that useful and causes
unnecessary differences between builds that you have to cope with, e.g.
if you want to ensure that a binary you got matches the source code.
Some Linux distributions are working on making builds reproducible for
precisely that reason and we all have to special-case these timestamps
or fix every single invocation of javadoc, so this seems to be the
obvious solution.
If someone really does need it, they can use the new '-timestamp' argument
or just check the timestamp on the file.
---
Hi there,
I'm not totally sure if this is the right channel to submit such a patch,
so feel free to tell me if I should put it somewhere else.
Also, I don't normally write java, but this was pretty simple and
it does indeed pass the testsuite here.
Please preserve the cc if you have any comments, as I'm currently not subscribed to this list.
Greetings,
Benedikt
.../doclets/formats/html/FrameOutputWriter.java | 4 +-
.../doclets/formats/html/HtmlDocletWriter.java | 4 +-
.../doclets/formats/html/markup/HtmlDocWriter.java | 6 +--
.../formats/html/resources/standard.properties | 2 +-
.../doclets/internal/toolkit/Configuration.java | 12 ++---
test/com/sun/javadoc/MetaTag/MetaTag.java | 60 +++++++++++-----------
.../sun/javadoc/VersionNumber/VersionNumber.java | 1 +
test/com/sun/javadoc/lib/JavadocTester.java | 7 ---
.../testCmndLineClass/TestCmndLineClass.java | 2 -
.../javadoc/testDocEncoding/TestDocEncoding.java | 1 -
.../javadoc/testGeneratedBy/TestGeneratedBy.java | 2 +-
.../sun/javadoc/testHelpOption/TestHelpOption.java | 1 -
.../sun/javadoc/testSourceTab/TestSourceTab.java | 2 -
13 files changed, 46 insertions(+), 58 deletions(-)
diff --git a/src/share/classes/com/sun/tools/doclets/formats/html/FrameOutputWriter.java b/src/share/classes/com/sun/tools/doclets/formats/html/FrameOutputWriter.java
index d6665e1..7192f3d 100644
--- a/src/share/classes/com/sun/tools/doclets/formats/html/FrameOutputWriter.java
+++ b/src/share/classes/com/sun/tools/doclets/formats/html/FrameOutputWriter.java
@@ -98,11 +98,11 @@ public class FrameOutputWriter extends HtmlDocletWriter {
protected void generateFrameFile() throws IOException {
Content frameset = getFrameDetails();
if (configuration.windowtitle.length() > 0) {
- printFramesetDocument(configuration.windowtitle, configuration.notimestamp,
+ printFramesetDocument(configuration.windowtitle, configuration.timestamp,
frameset);
} else {
printFramesetDocument(configuration.getText("doclet.Generated_Docs_Untitled"),
- configuration.notimestamp, frameset);
+ configuration.timestamp, frameset);
}
}
diff --git a/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java b/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java
index 78f1472..0a22904 100644
--- a/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java
+++ b/src/share/classes/com/sun/tools/doclets/formats/html/HtmlDocletWriter.java
@@ -396,14 +396,14 @@ public class HtmlDocletWriter extends HtmlDocWriter {
Content htmlDocType = DocType.TRANSITIONAL;
Content htmlComment = new Comment(configuration.getText("doclet.New_Page"));
Content head = new HtmlTree(HtmlTag.HEAD);
- head.addContent(getGeneratedBy(!configuration.notimestamp));
+ head.addContent(getGeneratedBy(configuration.timestamp));
if (configuration.charset.length() > 0) {
Content meta = HtmlTree.META("Content-Type", CONTENT_TYPE,
configuration.charset);
head.addContent(meta);
}
head.addContent(getTitle());
- if (!configuration.notimestamp) {
+ if (configuration.timestamp) {
SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
Content meta = HtmlTree.META("date", dateFormat.format(new Date()));
head.addContent(meta);
diff --git a/src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlDocWriter.java b/src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlDocWriter.java
index 1ddf6e6..3e06856 100644
--- a/src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlDocWriter.java
+++ b/src/share/classes/com/sun/tools/doclets/formats/html/markup/HtmlDocWriter.java
@@ -302,15 +302,15 @@ public abstract class HtmlDocWriter extends HtmlWriter {
* Called only when generating an HTML frameset file.
*
* @param title Title of this HTML document
- * @param noTimeStamp If true, don't print time stamp in header
+ * @param TimeStamp If true, print time stamp in header
* @param frameset the frameset to be added to the HTML document
*/
- public void printFramesetDocument(String title, boolean noTimeStamp,
+ public void printFramesetDocument(String title, boolean TimeStamp,
Content frameset) throws IOException {
Content htmlDocType = DocType.FRAMESET;
Content htmlComment = new Comment(configuration.getText("doclet.New_Page"));
Content head = new HtmlTree(HtmlTag.HEAD);
- head.addContent(getGeneratedBy(!noTimeStamp));
+ head.addContent(getGeneratedBy(TimeStamp));
if (configuration.charset.length() > 0) {
Content meta = HtmlTree.META("Content-Type", CONTENT_TYPE,
configuration.charset);
diff --git a/src/share/classes/com/sun/tools/doclets/formats/html/resources/standard.properties b/src/share/classes/com/sun/tools/doclets/formats/html/resources/standard.properties
index 9951877..9dbd8d3 100644
--- a/src/share/classes/com/sun/tools/doclets/formats/html/resources/standard.properties
+++ b/src/share/classes/com/sun/tools/doclets/formats/html/resources/standard.properties
@@ -206,7 +206,6 @@ doclet.usage=Provided by Standard doclet:\n\
\ -nodeprecated Do not include @deprecated information\n\
\ -noqualifier <name1>:<name2>:... Exclude the list of qualifiers from the output.\n\
\ -nosince Do not include @since information\n\
-\ -notimestamp Do not include hidden time stamp\n\
\ -nodeprecatedlist Do not generate deprecated list\n\
\ -notree Do not generate class hierarchy\n\
\ -noindex Do not generate index\n\
@@ -221,6 +220,7 @@ doclet.usage=Provided by Standard doclet:\n\
\ -linksource Generate source in HTML\n\
\ -sourcetab <tab length> Specify the number of spaces each tab takes up in the source\n\
\ -keywords Include HTML meta tags with package, class and member info\n\
+\ -timestamp Include hidden time stamp\n\
\ -stylesheetfile <path> File to change style of the generated documentation\n\
\ -docencoding <name> Specify the character encoding for the output
diff --git a/src/share/classes/com/sun/tools/doclets/internal/toolkit/Configuration.java b/src/share/classes/com/sun/tools/doclets/internal/toolkit/Configuration.java
index 27154a7..15c642c 100644
--- a/src/share/classes/com/sun/tools/doclets/internal/toolkit/Configuration.java
+++ b/src/share/classes/com/sun/tools/doclets/internal/toolkit/Configuration.java
@@ -251,10 +251,10 @@ public abstract class Configuration {
public MessageRetriever message = null;
/**
- * True if user wants to suppress time stamp in output.
+ * True if user wants a time stamp in output.
* Default is false.
*/
- public boolean notimestamp= false;
+ public boolean timestamp= false;
/**
* The package grouping instance.
@@ -335,7 +335,7 @@ public abstract class Configuration {
* which want to inherit from this Configuration. This method
* should return the number of arguments to the command line
* option (including the option name). For example,
- * -notimestamp is a single-argument option, so this method would
+ * -timestamp is a single-argument option, so this method would
* return 1.
*
* @param option Command line option under consideration.
@@ -354,7 +354,7 @@ public abstract class Configuration {
case "-nocomment":
case "-nodeprecated":
case "-nosince":
- case "-notimestamp":
+ case "-timestamp":
case "-quiet":
case "-xnodate":
case "-version":
@@ -507,8 +507,8 @@ public abstract class Configuration {
message.warning("doclet.sourcetab_warning");
setTabWidth(DocletConstants.DEFAULT_TAB_STOP_LENGTH);
}
- } else if (opt.equals("-notimestamp")) {
- notimestamp = true;
+ } else if (opt.equals("-timestamp")) {
+ timestamp = true;
} else if (opt.equals("-nocomment")) {
nocomment = true;
} else if (opt.equals("-tag") || opt.equals("-taglet")) {
diff --git a/test/com/sun/javadoc/MetaTag/MetaTag.java b/test/com/sun/javadoc/MetaTag/MetaTag.java
index 2a14fbd..f335042 100644
--- a/test/com/sun/javadoc/MetaTag/MetaTag.java
+++ b/test/com/sun/javadoc/MetaTag/MetaTag.java
@@ -49,9 +49,39 @@ public class MetaTag extends JavadocTester {
@Test
void testStandard() {
+ javadoc("-d", "out-2",
+ "-sourcepath", testSrc,
+ "-doctitle", "Sample Packages",
+ "p1", "p2");
+ checkExit(Exit.OK);
+
+ // No keywords when -keywords is not used.
+ checkOutput("p1/C1.html", false,
+ "<META NAME=\"keywords\" CONTENT=\"p1.C1 class\">",
+ "<META NAME=\"keywords\" CONTENT=\"field1\">",
+ "<META NAME=\"keywords\" CONTENT=\"field2\">",
+ "<META NAME=\"keywords\" CONTENT=\"method1()\">",
+ "<META NAME=\"keywords\" CONTENT=\"method2()\">");
+
+ checkOutput("p1/package-summary.html", false,
+ "<META NAME=\"keywords\" CONTENT=\"p1 package\">");
+
+ checkOutput("overview-summary.html", false,
+ "<META NAME=\"keywords\" CONTENT=\"Overview Summary, Sample Packages\">");
+
+ // The date metatag should not show up when -timestamp is not used.
+ // NOTE: Hopefully, this regression test is not run at midnight. If the output
+ // was generated yesterday and this test is run today, the test will fail.
+ checkOutput("overview-summary.html", false,
+ "<META NAME=\"date\" CONTENT=\"" + date() + "\">");
+ }
+
+ @Test
+ void testTimestamp() {
javadoc("-d", "out-1",
"-sourcepath", testSrc,
"-keywords",
+ "-timestamp",
"-doctitle", "Sample Packages",
"p1", "p2");
@@ -76,36 +106,6 @@ public class MetaTag extends JavadocTester {
"<meta name=\"date\" content=\"" + date() + "\">");
}
- @Test
- void testNoTimestamp() {
- javadoc("-d", "out-2",
- "-sourcepath", testSrc,
- "-notimestamp",
- "-doctitle", "Sample Packages",
- "p1", "p2");
- checkExit(Exit.OK);
-
- // No keywords when -keywords is not used.
- checkOutput("p1/C1.html", false,
- "<META NAME=\"keywords\" CONTENT=\"p1.C1 class\">",
- "<META NAME=\"keywords\" CONTENT=\"field1\">",
- "<META NAME=\"keywords\" CONTENT=\"field2\">",
- "<META NAME=\"keywords\" CONTENT=\"method1()\">",
- "<META NAME=\"keywords\" CONTENT=\"method2()\">");
-
- checkOutput("p1/package-summary.html", false,
- "<META NAME=\"keywords\" CONTENT=\"p1 package\">");
-
- checkOutput("overview-summary.html", false,
- "<META NAME=\"keywords\" CONTENT=\"Overview Summary, Sample Packages\">");
-
- // The date metatag should not show up when -notimestamp is used.
- // NOTE: Hopefully, this regression test is not run at midnight. If the output
- // was generated yesterday and this test is run today, the test will fail.
- checkOutput("overview-summary.html", false,
- "<META NAME=\"date\" CONTENT=\"" + date() + "\">");
- }
-
private static final SimpleDateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
String date() {
diff --git a/test/com/sun/javadoc/VersionNumber/VersionNumber.java b/test/com/sun/javadoc/VersionNumber/VersionNumber.java
index 7089e50..7aa2400 100644
--- a/test/com/sun/javadoc/VersionNumber/VersionNumber.java
+++ b/test/com/sun/javadoc/VersionNumber/VersionNumber.java
@@ -45,6 +45,7 @@ public class VersionNumber extends JavadocTester {
@Test
void test() {
javadoc("-d", "out",
+ "-timestamp",
"p1");
checkExit(Exit.OK);
diff --git a/test/com/sun/javadoc/lib/JavadocTester.java b/test/com/sun/javadoc/lib/JavadocTester.java
index aa12176..d2a337e 100644
--- a/test/com/sun/javadoc/lib/JavadocTester.java
+++ b/test/com/sun/javadoc/lib/JavadocTester.java
@@ -98,12 +98,6 @@ import java.util.Map;
* </code></pre>
*
* <p>
- * If javadoc is run more than once in a test method, you can compare the
- * results that are generated with the diff method. Since files written by
- * javadoc typically contain a timestamp, you may want to use the -notimestamp
- * option if you are going to compare the results from two runs of javadoc.
- *
- * <p>
* If you have many calls of checkOutput that are very similar, you can write
* your own check... method to reduce the amount of duplication. For example,
* if you want to check that many files contain the same string, you could
@@ -266,7 +260,6 @@ public abstract class JavadocTester {
* <pre><code>
* javadoc("-d", "out",
* "-sourcepath", testSrc,
- * "-notimestamp",
* "pkg1", "pkg2", "pkg3/C.java");
* </code></pre>
*
diff --git a/test/com/sun/javadoc/testCmndLineClass/TestCmndLineClass.java b/test/com/sun/javadoc/testCmndLineClass/TestCmndLineClass.java
index e21ca6b..c2ae981 100644
--- a/test/com/sun/javadoc/testCmndLineClass/TestCmndLineClass.java
+++ b/test/com/sun/javadoc/testCmndLineClass/TestCmndLineClass.java
@@ -47,13 +47,11 @@ public class TestCmndLineClass extends JavadocTester {
javadoc("-d", outdir1,
"-sourcepath", testSrc,
- "-notimestamp",
testSrc("C5.java"), "pkg1", "pkg2");
checkExit(Exit.OK);
javadoc("-d", outdir2,
"-sourcepath", testSrc,
- "-notimestamp",
testSrc("C5.java"),
testSrc("pkg1/C1.java"),
testSrc("pkg1/C2.java"),
diff --git a/test/com/sun/javadoc/testDocEncoding/TestDocEncoding.java b/test/com/sun/javadoc/testDocEncoding/TestDocEncoding.java
index 2a9eea8..fae5a4e 100644
--- a/test/com/sun/javadoc/testDocEncoding/TestDocEncoding.java
+++ b/test/com/sun/javadoc/testDocEncoding/TestDocEncoding.java
@@ -48,7 +48,6 @@ public class TestDocEncoding extends JavadocTester {
javadoc("-d", "out",
"-docencoding", "Cp930",
"-sourcepath", testSrc,
- "-notimestamp",
"pkg");
checkExit(Exit.OK);
diff --git a/test/com/sun/javadoc/testGeneratedBy/TestGeneratedBy.java b/test/com/sun/javadoc/testGeneratedBy/TestGeneratedBy.java
index bde5bbe..6c814ed 100644
--- a/test/com/sun/javadoc/testGeneratedBy/TestGeneratedBy.java
+++ b/test/com/sun/javadoc/testGeneratedBy/TestGeneratedBy.java
@@ -40,6 +40,7 @@ public class TestGeneratedBy extends JavadocTester {
@Test
void testTimestamp() {
javadoc("-d", "out-timestamp",
+ "-timestamp",
"-sourcepath", testSrc,
"pkg");
checkExit(Exit.OK);
@@ -50,7 +51,6 @@ public class TestGeneratedBy extends JavadocTester {
@Test
void testNoTimestamp() {
javadoc("-d", "out-notimestamp",
- "-notimestamp",
"-sourcepath", testSrc,
"pkg");
checkExit(Exit.OK);
diff --git a/test/com/sun/javadoc/testHelpOption/TestHelpOption.java b/test/com/sun/javadoc/testHelpOption/TestHelpOption.java
index 9c571d6..d21d3c9 100644
--- a/test/com/sun/javadoc/testHelpOption/TestHelpOption.java
+++ b/test/com/sun/javadoc/testHelpOption/TestHelpOption.java
@@ -81,7 +81,6 @@ public class TestHelpOption extends JavadocTester {
"-nodeprecated ",
"-noqualifier ",
"-nosince ",
- "-notimestamp ",
"-nodeprecatedlist ",
"-notree ",
"-noindex ",
diff --git a/test/com/sun/javadoc/testSourceTab/TestSourceTab.java b/test/com/sun/javadoc/testSourceTab/TestSourceTab.java
index 1364ece..858ff38 100644
--- a/test/com/sun/javadoc/testSourceTab/TestSourceTab.java
+++ b/test/com/sun/javadoc/testSourceTab/TestSourceTab.java
@@ -51,7 +51,6 @@ public class TestSourceTab extends JavadocTester {
// Run Javadoc on a source file with that is indented with a single tab per line
javadoc("-d", outdir1,
"-sourcepath", tmpSrcDir,
- "-notimestamp",
"-linksource",
tmpSrcDir + "/SingleTab/C.java");
checkExit(Exit.OK);
@@ -61,7 +60,6 @@ public class TestSourceTab extends JavadocTester {
// be the same as the one generated above.
javadoc("-d", outdir2,
"-sourcepath", tmpSrcDir,
- "-notimestamp",
"-sourcetab", "4",
tmpSrcDir + "/DoubleTab/C.java");
checkExit(Exit.OK);
--
1.9.3
More information about the javadoc-dev
mailing list