Browse files

Javadoc

  • Loading branch information...
1 parent b04d809 commit b161f07fbc4d836cd2ff51a48719b2925f57535b @jodastephen jodastephen committed Nov 30, 2012
View
29 src/main/java/javax/time/OffsetDate.java
@@ -59,7 +59,7 @@
import javax.time.zone.ZoneResolvers;
/**
- * A date with a zone offset from UTC/Greenwich in the ISO-8601 calendar system,
+ * A date with an offset from UTC/Greenwich in the ISO-8601 calendar system,
* such as {@code 2007-12-03+01:00}.
* <p>
* {@code OffsetDate} is an immutable date-time object that represents a date, often viewed
@@ -83,11 +83,11 @@
private static final long serialVersionUID = -4382054179074397774L;
/**
- * The date, not null.
+ * The local date.
*/
private final LocalDate date;
/**
- * The zone offset, not null.
+ * The offset from UTC/Greenwich.
*/
private final ZoneOffset offset;
@@ -167,6 +167,7 @@ public static OffsetDate of(int year, int month, int dayOfMonth, ZoneOffset offs
return new OffsetDate(date, offset);
}
+ //-----------------------------------------------------------------------
/**
* Obtains an instance of {@code OffsetDate} from a local date and an offset.
*
@@ -232,8 +233,8 @@ public static OffsetDate parse(CharSequence text, DateTimeFormatter formatter) {
/**
* Constructor.
*
- * @param date the date, validated as not null
- * @param offset the zone offset, validated as not null
+ * @param date the local date, not null
+ * @param offset the zone offset, not null
*/
private OffsetDate(LocalDate date, ZoneOffset offset) {
this.date = Objects.requireNonNull(date, "date");
@@ -286,7 +287,9 @@ public long getLong(DateTimeField field) {
//-----------------------------------------------------------------------
/**
- * Gets the zone offset.
+ * Gets the zone offset, such as '+01:00'.
+ * <p>
+ * This is the offset of the local date from UTC/Greenwich.
*
* @return the zone offset, not null
*/
@@ -795,7 +798,7 @@ public OffsetDate minusDays(long days) {
* <p>
* This instance is immutable and unaffected by this method call.
*
- * @param time the time to use, not null
+ * @param time the time to combine with, not null
* @return the offset date-time formed from this date and the specified time, not null
*/
public OffsetDateTime atTime(OffsetTime time) {
@@ -810,7 +813,7 @@ public OffsetDateTime atTime(OffsetTime time) {
* <p>
* This instance is immutable and unaffected by this method call.
*
- * @param time the time to use, not null
+ * @param time the time to combine with, not null
* @return the offset date-time formed from this date and the specified time, not null
*/
public OffsetDateTime atTime(LocalTime time) {
@@ -1098,14 +1101,14 @@ private Object writeReplace() {
}
void writeExternal(DataOutput out) throws IOException {
- date.writeExternal(out);
- offset.writeExternal(out);
+ date.writeExternal(out);
+ offset.writeExternal(out);
}
static OffsetDate readExternal(DataInput in) throws IOException {
- LocalDate date = LocalDate.readExternal(in);
- ZoneOffset offset = ZoneOffset.readExternal(in);
- return OffsetDate.of(date, offset);
+ LocalDate date = LocalDate.readExternal(in);
+ ZoneOffset offset = ZoneOffset.readExternal(in);
+ return OffsetDate.of(date, offset);
}
}
View
14 src/main/java/javax/time/OffsetDateTime.java
@@ -56,7 +56,7 @@
import javax.time.zone.ZoneRules;
/**
- * A date-time with a zone offset from UTC/Greenwich in the ISO-8601 calendar system,
+ * A date-time with an offset from UTC/Greenwich in the ISO-8601 calendar system,
* such as {@code 2007-12-03T10:15:30+01:00}.
* <p>
* {@code OffsetDateTime} is an immutable representation of a date-time with an offset.
@@ -84,11 +84,11 @@
private static final long serialVersionUID = 2287754244819255394L;
/**
- * The local date-time, not null.
+ * The local date-time.
*/
private final LocalDateTime dateTime;
/**
- * The zone offset, not null.
+ * The offset from UTC/Greenwich.
*/
private final ZoneOffset offset;
@@ -460,14 +460,12 @@ public static OffsetDateTime parse(CharSequence text, DateTimeFormatter formatte
/**
* Constructor.
*
- * @param dateTime the date-time, not null
+ * @param time the local date-time, not null
* @param offset the zone offset, not null
*/
private OffsetDateTime(LocalDateTime dateTime, ZoneOffset offset) {
- Objects.requireNonNull(dateTime, "dateTime");
- Objects.requireNonNull(offset, "offset");
- this.dateTime = dateTime;
- this.offset = offset;
+ this.dateTime = Objects.requireNonNull(dateTime, "dateTime");
+ this.offset = Objects.requireNonNull(offset, "offset");
}
/**
View
15 src/main/java/javax/time/OffsetTime.java
@@ -59,7 +59,7 @@
import javax.time.jdk8.DefaultInterfaceDateTimeAccessor;
/**
- * A time with a zone offset from UTC/Greenwich in the ISO-8601 calendar system,
+ * A time with an offset from UTC/Greenwich in the ISO-8601 calendar system,
* such as {@code 10:15:30+01:00}.
* <p>
* {@code OffsetTime} is an immutable date-time object that represents a time, often
@@ -82,11 +82,11 @@
private static final long serialVersionUID = 7264499704384272492L;
/**
- * The local time, not null.
+ * The local date-time.
*/
private final LocalTime time;
/**
- * The zone offset, not null.
+ * The offset from UTC/Greenwich.
*/
private final ZoneOffset offset;
@@ -175,6 +175,7 @@ public static OffsetTime of(int hour, int minute, int second, int nanoOfSecond,
return new OffsetTime(time, offset);
}
+ //-----------------------------------------------------------------------
/**
* Obtains an instance of {@code OffsetTime} from a local time and an offset.
*
@@ -264,8 +265,8 @@ public static OffsetTime parse(CharSequence text, DateTimeFormatter formatter) {
/**
* Constructor.
*
- * @param time the time, validated as not null
- * @param offset the zone offset, validated as not null
+ * @param time the local time, not null
+ * @param offset the zone offset, not null
*/
private OffsetTime(LocalTime time, ZoneOffset offset) {
this.time = Objects.requireNonNull(time, "time");
@@ -318,7 +319,9 @@ public long getLong(DateTimeField field) {
//-----------------------------------------------------------------------
/**
- * Gets the zone offset representing how far ahead or behind UTC the time is.
+ * Gets the zone offset, such as '+01:00'.
+ * <p>
+ * This is the offset of the local time from UTC/Greenwich.
*
* @return the zone offset, not null
*/
View
34 src/main/java/javax/time/ZonedDateTime.java
@@ -122,7 +122,7 @@ public static ZonedDateTime now() {
/**
* Obtains the current date-time from the specified clock.
* <p>
- * This will query the specified clock to obtain the current time.
+ * This will query the specified clock to obtain the current date-time.
* The zone and offset will be set based on the time-zone in the clock.
* <p>
* Using this method allows the use of an alternate clock for testing.
@@ -483,6 +483,9 @@ private static ZonedDateTime create(long epochSecond, int nanoOfSecond, ZoneId z
* <p>
* A {@code DateTimeAccessor} represents some form of date and time information.
* This factory converts the arbitrary date-time object to an instance of {@code ZonedDateTime}.
+ * <p>
+ * The conversion will try to obtain an instant first, then try to obtain the
+ * local date-time.
*
* @param dateTime the date-time object to convert, not null
* @return the zoned date-time, not null
@@ -705,7 +708,8 @@ public ZonedDateTime withLaterOffsetAtOverlap() {
/**
* Gets the time-zone, such as 'Europe/Paris'.
* <p>
- * This returns the stored time-zone ID used to determine the time-zone rules.
+ * This returns the zone ID. This identifies the time-zone rules that
+ * determine when and how the offset from UTC/Greenwich changes.
*
* @return the time-zone, not null
*/
@@ -715,7 +719,7 @@ public ZoneId getZone() {
}
/**
- * Returns a copy of this ZonedDateTime with a different time-zone,
+ * Returns a copy of this date-time with a different time-zone,
* retaining the local date-time if possible.
* <p>
* This method changes the time-zone and retains the local date-time.
@@ -736,7 +740,7 @@ public ZonedDateTime withZoneSameLocal(ZoneId zone) {
}
/**
- * Returns a copy of this ZonedDateTime with a different time-zone,
+ * Returns a copy of this date-time with a different time-zone,
* retaining the local date-time if possible.
* <p>
* This method changes the time-zone and retains the local date-time.
@@ -761,7 +765,7 @@ public ZonedDateTime withZoneSameLocal(ZoneId zone, ZoneResolver resolver) {
}
/**
- * Returns a copy of this ZonedDateTime with a different time-zone,
+ * Returns a copy of this date-time with a different time-zone,
* retaining the instant.
* <p>
* This method changes the time-zone and retains the instant.
@@ -1483,6 +1487,7 @@ public ZonedDateTime plusDays(long days) {
resolve(newDT, zone, dateTime, ZoneResolvers.retainOffset()));
}
+ //-----------------------------------------------------------------------
/**
* Returns a copy of this {@code ZonedDateTime} with the specified period in hours added.
* <p>
@@ -1569,12 +1574,11 @@ public ZonedDateTime plusNanos(long nanos) {
/**
* Returns a copy of this {@code ZonedDateTime} with the specified duration added.
* <p>
- * Adding a duration differs from adding a period as gaps and overlaps in
- * the local time-line are taken into account. For example, if there is a
- * gap in the local time-line of one hour from 01:00 to 02:00, then adding a
- * duration of one hour to 00:30 will yield 02:30.
+ * The addition is performed on the underlying instant using the zone ID.
+ * For example, if there is a gap in the local time-line of one hour from
+ * 01:00 to 02:00, then adding a duration of one hour to 00:30 will yield 02:30.
* <p>
- * The addition of a duration is always absolute and zone-resolvers are not required.
+ * The addition of a duration is always absolute with no special cases due to time-zones.
* <p>
* This instance is immutable and unaffected by this method call.
*
@@ -1737,6 +1741,7 @@ public ZonedDateTime minusDays(long days) {
return (days == Long.MIN_VALUE ? plusDays(Long.MAX_VALUE).plusDays(1) : plusDays(-days));
}
+ //-----------------------------------------------------------------------
/**
* Returns a copy of this {@code ZonedDateTime} with the specified period in hours subtracted.
* <p>
@@ -1815,12 +1820,11 @@ public ZonedDateTime minusNanos(long nanos) {
/**
* Returns a copy of this {@code ZonedDateTime} with the specified duration subtracted.
* <p>
- * Subtracting a duration differs from subtracting a period as gaps and overlaps in
- * the local time-line are taken into account. For example, if there is a
- * gap in the local time-line of one hour from 01:00 to 02:00, then subtracting a
- * duration of one hour from 02:30 will yield 00:30.
+ * The subtraction is performed on the underlying instant using the zone ID.
+ * For example, if there is a gap in the local time-line of one hour from
+ * 01:00 to 02:00, then subtracting a duration of one hour from 02:30 will yield 00:30.
* <p>
- * The subtraction of a duration is always absolute and zone-resolvers are not required.
+ * The subtraction of a duration is always absolute with no special cases due to time-zones.
* <p>
* This instance is immutable and unaffected by this method call.
*

0 comments on commit b161f07

Please sign in to comment.