jdk-sandbox: comparison jdk/src/share/classes/java/time/temporal/WeekFields.java

equal deleted inserted replaced

-:35cd9b3a98ff
+:8c100beabcc0
 * <tr><th>2009-01-04</th><td>Sunday</td>
 *  <td>Week 1 of 2009</td><td>Week 53 of 2008</td></tr>
 * <tr><th>2009-01-05</th><td>Monday</td>
 *  <td>Week 2 of 2009</td><td>Week 1 of 2009</td></tr>
 * </table>
-* <h3>Specification for implementors</h3>
+*
+* @implSpec
 * This class is immutable and thread-safe.
 *
 * @since 1.8
 */
 public final class WeekFields implements Serializable {
 * up the passage of days instead of the standard year/month/day.
 * <p>
 * Note that the first week may start in the previous calendar year.
 * Note also that the first few days of a calendar year may be in the
 * week-based-year corresponding to the previous calendar year.
-* <p>
-* This field is an immutable and thread-safe singleton.
 */
 public static final WeekFields ISO = new WeekFields(DayOfWeek.MONDAY, 4);
 /**
 * The common definition of a week that starts on Sunday and the first week
 * has a minimum of 1 day.
 * <p>
 * Defined as starting on Sunday and with a minimum of 1 day in the month.
 * This week definition is in use in the US and other European countries.
-* <p>
-* This field is an immutable and thread-safe singleton.
 */
 public static final WeekFields SUNDAY_START = WeekFields.of(DayOfWeek.SUNDAY, 1);
 /**
 * The unit that represents week-based-years for the purpose of addition and subtraction.
 * for the week-based-year field retaining the week-of-week-based-year
 * and day-of-week, unless the week number it too large for the target year.
 * In that case, the week is set to the last week of the year
 * with the same day-of-week.
 * <p>
-* This field is an immutable and thread-safe singleton.
+* This unit is an immutable and thread-safe singleton.
 */
 public static final TemporalUnit WEEK_BASED_YEARS = IsoFields.WEEK_BASED_YEARS;
 /**
 * Serialization version.
 private final DayOfWeek firstDayOfWeek;
 /**
 * The minimal number of days in the first week.
 */
 private final int minimalDays;
 /**
 * The field used to access the computed DayOfWeek.
 */
 private transient final TemporalField dayOfWeek = ComputedDayOfField.ofDayOfWeekField(this);
 /**
 * The field used to access the computed WeekOfMonth.
 */
 private transient final TemporalField weekOfMonth = ComputedDayOfField.ofWeekOfMonthField(this);
 /**
 * The field used to access the computed WeekOfYear.
 */
 private transient final TemporalField weekOfYear = ComputedDayOfField.ofWeekOfYearField(this);
 /**
 * The field that represents the week-of-week-based-year.
 * <p>
 * This field allows the week of the week-based-year value to be queried and set.
 * <p>
 * This unit is an immutable and thread-safe singleton.
 */
 private transient final TemporalField weekOfWeekBasedYear = ComputedDayOfField.ofWeekOfWeekBasedYearField(this);
 /**
 * The field that represents the week-based-year.
 * <p>
 * This field allows the week-based-year value to be queried and set.
 * <p>
 * This unit is an immutable and thread-safe singleton.
 */
 private transient final TemporalField weekBasedYear = ComputedDayOfField.ofWeekBasedYearField(this);
+//-----------------------------------------------------------------------
 /**
 * Obtains an instance of {@code WeekFields} appropriate for a locale.
 * <p>
 * This will look up appropriate values from the provider of localization data.
 *
 */
 private Object readResolve() throws InvalidObjectException {
 try {
 return WeekFields.of(firstDayOfWeek, minimalDays);
 } catch (IllegalArgumentException iae) {
-throw new InvalidObjectException("Invalid serialized WeekFields: "
+throw new InvalidObjectException("Invalid serialized WeekFields: " + iae.getMessage());
-+ iae.getMessage());
 }
 }
 //-----------------------------------------------------------------------
 /**
 return minimalDays;
 }
 //-----------------------------------------------------------------------
 /**
-* Returns a field to access the day of week,
+* Returns a field to access the day of week based on this {@code WeekFields}.
-* computed based on this WeekFields.
+* <p>
-* <p>
+* This is similar to {@link ChronoField#DAY_OF_WEEK} but uses values for
-* The days of week are numbered from 1 to 7.
+* the day-of-week based on this {@code WeekFields}.
-* Day number 1 is the {@link #getFirstDayOfWeek() first day-of-week}.
+* The days are numbered from 1 to 7 where the
-*
+* {@link #getFirstDayOfWeek() first day-of-week} is assigned the value 1.
-* @return the field for day-of-week using this week definition, not null
+* <p>
+* For example, if the first day-of-week is Sunday, then that will have the
+* value 1, with other days ranging from Monday as 2 to Saturday as 7.
+*
+* @return a field providing access to the day-of-week with localized numbering, not null
 */
 public TemporalField dayOfWeek() {
 return dayOfWeek;
 }
 /**
-* Returns a field to access the week of month,
+* Returns a field to access the week of month based on this {@code WeekFields}.
-* computed based on this WeekFields.
 * <p>
 * This represents the concept of the count of weeks within the month where weeks
 * start on a fixed day-of-week, such as Monday.
 * This field is typically used with {@link WeekFields#dayOfWeek()}.
 * <p>
 * - if the 2nd day of the month is a Monday, week one starts on the 2nd and the 1st is in week zero<br>
 * - if the 4th day of the month is a Monday, week one starts on the 4th and the 1st to 3rd is in week zero<br>
 * - if the 5th day of the month is a Monday, week two starts on the 5th and the 1st to 4th is in week one<br>
 * <p>
 * This field can be used with any calendar system.
-* @return a TemporalField to access the WeekOfMonth, not null
+*
+* @return a field providing access to the week-of-month, not null
 */
 public TemporalField weekOfMonth() {
 return weekOfMonth;
 }
 /**
-* Returns a field to access the week of year,
+* Returns a field to access the week of year based on this {@code WeekFields}.
-* computed based on this WeekFields.
 * <p>
 * This represents the concept of the count of weeks within the year where weeks
 * start on a fixed day-of-week, such as Monday.
 * This field is typically used with {@link WeekFields#dayOfWeek()}.
 * <p>
 * - if the 2nd day of the year is a Monday, week one starts on the 2nd and the 1st is in week zero<br>
 * - if the 4th day of the year is a Monday, week one starts on the 4th and the 1st to 3rd is in week zero<br>
 * - if the 5th day of the year is a Monday, week two starts on the 5th and the 1st to 4th is in week one<br>
 * <p>
 * This field can be used with any calendar system.
-* @return a TemporalField to access the WeekOfYear, not null
+*
+* @return a field providing access to the week-of-year, not null
 */
 public TemporalField weekOfYear() {
 return weekOfYear;
 }
 /**
-* Returns a field to access the week of a week-based-year,
+* Returns a field to access the week of a week-based-year based on this {@code WeekFields}.
-* computed based on this WeekFields.
 * <p>
 * This represents the concept of the count of weeks within the year where weeks
 * start on a fixed day-of-week, such as Monday and each week belongs to exactly one year.
 * This field is typically used with {@link WeekFields#dayOfWeek()} and
 * {@link WeekFields#weekBasedYear()}.
 *   the 1st to 3rd is in the last week of the previous year<br>
 * - if the 5th day of the year is a Monday, week two starts on the 5th and
 *   the 1st to 4th is in week one<br>
 * <p>
 * This field can be used with any calendar system.
-* @return a TemporalField to access the week of week-based-year, not null
+*
+* @return a field providing access to the week-of-week-based-year, not null
 */
 public TemporalField weekOfWeekBasedYear() {
 return weekOfWeekBasedYear;
 }
 /**
-* Returns a field to access the year of a week-based-year,
+* Returns a field to access the year of a week-based-year based on this {@code WeekFields}.
-* computed based on this WeekFields.
 * <p>
 * This represents the concept of the year where weeks start on a fixed day-of-week,
 * such as Monday and each week belongs to exactly one year.
 * This field is typically used with {@link WeekFields#dayOfWeek()} and
 * {@link WeekFields#weekOfWeekBasedYear()}.
 * Thus, week one may start before the start of the year.
 * If the first week starts after the start of the year then the period before
 * is in the last week of the previous year.
 * <p>
 * This field can be used with any calendar system.
-* @return a TemporalField to access the year of week-based-year, not null
+*
+* @return a field providing access to the week-based-year, not null
 */
 public TemporalField weekBasedYear() {
 return weekBasedYear;
 }
-/**
+//-----------------------------------------------------------------------
-* Checks if this WeekFields is equal to the specified object.
+/**
+* Checks if this {@code WeekFields} is equal to the specified object.
 * <p>
 * The comparison is based on the entire state of the rules, which is
 * the first day-of-week and minimal days.
 *
 * @param object  the other rules to compare to, null returns false
 }
 return false;
 }
 /**
-* A hash code for these rules.
+* A hash code for this {@code WeekFields}.
 *
 * @return a suitable hash code
 */
 @Override
 public int hashCode() {
 return firstDayOfWeek.ordinal() * 7 + minimalDays;
 }
 //-----------------------------------------------------------------------
 /**
-* A string representation of this definition.
+* A string representation of this {@code WeekFields} instance.
 *
 * @return the string representation, not null
 */
 @Override
 public String toString() {
 }
 /**
 * Map the field range to a week range of a week year.
 * @param temporal  the temporal
-* @param field  the field to get the range of
 * @return the ValueRange with the range adjusted to weeks.
 */
 private ValueRange rangeWeekOfWeekBasedYear(TemporalAccessor temporal) {
 if (!temporal.isSupported(DAY_OF_YEAR)) {
 return WEEK_OF_YEAR_RANGE;

changeset 17474	8c100beabcc0
parent 16852	60207b2b4b42
child 19030	32f129cb6351