6955047: (tz) javadoc for TimeZone.getDisplayName(boolean daylight, int style, Locale locale) is not clear
7021680: (tz) daylight savings time should be daylight saving time
Reviewed-by: peytoia
--- a/jdk/src/share/classes/java/util/Calendar.java Wed Feb 23 14:09:23 2011 +0900
+++ b/jdk/src/share/classes/java/util/Calendar.java Wed Feb 23 16:50:13 2011 +0900
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -554,7 +554,7 @@
/**
* Field number for <code>get</code> and <code>set</code> indicating the
- * daylight savings offset in milliseconds.
+ * daylight saving offset in milliseconds.
* <p>
* This field reflects the correct daylight saving offset value of
* the time zone of this <code>Calendar</code> if the
--- a/jdk/src/share/classes/java/util/GregorianCalendar.java Wed Feb 23 14:09:23 2011 +0900
+++ b/jdk/src/share/classes/java/util/GregorianCalendar.java Wed Feb 23 16:50:13 2011 +0900
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 1996, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1996, 2011, Oracle and/or its affiliates. All rights reserved.
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* This code is free software; you can redistribute it and/or modify it
@@ -260,7 +260,7 @@
* // create a Pacific Standard Time time zone
* SimpleTimeZone pdt = new SimpleTimeZone(-8 * 60 * 60 * 1000, ids[0]);
*
- * // set up rules for daylight savings time
+ * // set up rules for Daylight Saving Time
* pdt.setStartRule(Calendar.APRIL, 1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
* pdt.setEndRule(Calendar.OCTOBER, -1, Calendar.SUNDAY, 2 * 60 * 60 * 1000);
*
--- a/jdk/src/share/classes/java/util/TimeZone.java Wed Feb 23 14:09:23 2011 +0900
+++ b/jdk/src/share/classes/java/util/TimeZone.java Wed Feb 23 16:50:13 2011 +0900
@@ -339,8 +339,9 @@
/**
* Returns a name in the specified {@code style} of this {@code TimeZone}
* suitable for presentation to the user in the default locale. If the
- * specified {@code daylight} is {@code true}, a daylight saving time name
- * is returned. Otherwise, a standard time name is returned.
+ * specified {@code daylight} is {@code true}, a Daylight Saving Time name
+ * is returned (even if this {@code TimeZone} doesn't observe Daylight Saving
+ * Time). Otherwise, a Standard Time name is returned.
*
* <p>This method is equivalent to:
* <pre><blockquote>
@@ -348,7 +349,8 @@
* Locale.getDefault({@link Locale.Category#DISPLAY}))
* </blockquote></pre>
*
- * @param daylight if {@code true}, return the daylight saving time name.
+ * @param daylight {@code true} specifying a Daylight Saving Time name, or
+ * {@code false} specifying a Standard Time name
* @param style either {@link #LONG} or {@link #SHORT}
* @return the human-readable name of this time zone in the default locale.
* @exception IllegalArgumentException if {@code style} is invalid.
@@ -356,6 +358,7 @@
* @see #getDisplayName(boolean, int, Locale)
* @see Locale#getDefault(Locale.Category)
* @see Locale.Category
+ * @see java.text.DateFormatSymbols#getZoneStrings()
*/
public final String getDisplayName(boolean daylight, int style) {
return getDisplayName(daylight, style,
@@ -365,8 +368,9 @@
/**
* Returns a name in the specified {@code style} of this {@code TimeZone}
* suitable for presentation to the user in the specified {@code
- * locale}. If the specified {@code daylight} is {@code true}, a daylight
- * saving time name is returned. Otherwise, a standard time name is
+ * locale}. If the specified {@code daylight} is {@code true}, a Daylight
+ * Saving Time name is returned (even if this {@code TimeZone} doesn't
+ * observe Daylight Saving Time). Otherwise, a Standard Time name is
* returned.
*
* <p>When looking up a time zone name, the {@linkplain
@@ -379,13 +383,15 @@
* found, the name is returned. Otherwise, a string in the
* <a href="#NormalizedCustomID">normalized custom ID format</a> is returned.
*
- * @param daylight if {@code true}, return the daylight saving time name.
+ * @param daylight {@code true} specifying a Daylight Saving Time name, or
+ * {@code false} specifying a Standard Time name
* @param style either {@link #LONG} or {@link #SHORT}
- * @param locale the locale in which to supply the display name.
+ * @param locale the locale in which to supply the display name.
* @return the human-readable name of this time zone in the given locale.
* @exception IllegalArgumentException if {@code style} is invalid.
* @exception NullPointerException if {@code locale} is {@code null}.
* @since 1.2
+ * @see java.text.DateFormatSymbols#getZoneStrings()
*/
public String getDisplayName(boolean daylight, int style, Locale locale) {
if (style != SHORT && style != LONG) {
@@ -526,10 +532,10 @@
/**
* Queries if the given {@code date} is in Daylight Saving Time in
- * this {@code TimeZone}.
+ * this time zone.
*
- * @param date the given {@code Date}.
- * @return {@code true} if the given {@code date} is in Daylight Saving Time,
+ * @param date the given Date.
+ * @return {@code true} if the given date is in Daylight Saving Time,
* {@code false}, otherwise.
*/
abstract public boolean inDaylightTime(Date date);
@@ -566,7 +572,7 @@
* @param rawOffset the given time zone GMT offset in milliseconds.
* @return an array of IDs, where the time zone for that ID has
* the specified GMT offset. For example, "America/Phoenix" and "America/Denver"
- * both have GMT-07:00, but differ in daylight savings behavior.
+ * both have GMT-07:00, but differ in daylight saving behavior.
* @see #getRawOffset()
*/
public static synchronized String[] getAvailableIDs(int rawOffset) {