Adding Duration documentation, abs(), and isNegative()

sdk/lib/core/duration.dart

Index: sdk/lib/core/duration.dart
diff --git a/sdk/lib/core/duration.dart b/sdk/lib/core/duration.dart
index d174012baa5bfd869c2a227d51c7c83e563c0c1b..274215c0e3cca978960561f75bdf88db2dcc7d4e 100644
--- a/sdk/lib/core/duration.dart
+++ b/sdk/lib/core/duration.dart
@@ -208,15 +208,21 @@ class Duration implements Comparable<Duration> {
   int get hashCode => _duration.hashCode;
 
   /**
-   * Compares this Duration to [other],
-   * returning zero if the values are equal.
+   * Compares this Duration to [other], returning zero if the values are equal.
    *
-   * This function returns a negative integer
-   * if this Duration is smaller than [other],
-   * or a positive integer if it is greater.
+   * This function returns a negative integer if this Duration is smaller than

[Lasse Reichstein Nielsen, 2014/08/04 07:42:25]

"This function returns" -> "Returns"
Duration -> `Duration`
smaller -> shorter

[srawlins, 2014/08/04 21:45:09]

Done.

+   * [other], or a positive integer if it is greater.

[Lasse Reichstein Nielsen, 2014/08/04 07:42:25]

greater -> longer.

Add:
 * A negative `Duration` is always considered shorter than a positive one.
 *
 * It is always the case that `duration1.compareTo(duration2) < 0`
 * iff `(someDate + duration1).compareTo(someDate + duration2) < 0`.

[srawlins, 2014/08/04 21:45:09]

Done.

    */
   int compareTo(Duration other) => _duration.compareTo(other._duration);
 
+  /**
+   * Returns a string representation of this Duration with hours, minutes,

[Lasse Reichstein Nielsen, 2014/08/04 07:42:25]

Make a short first line, e.g.:

"Returns a string representation of this `Duration`.

Returns a string with hours, minutes, ..."

[srawlins, 2014/08/04 21:45:09]

Done.

+   * seconds, and microseconds, in the following format: `HH:MM:SS.mmmmmm`. For
+   * example,
+   *
+   *     var d = new Duration(days:1, hours:1, minutes:33, microseconds: 500);
+   *     d.toString();  // "25:33:00.000500"
+   */
   String toString() {
     String sixDigits(int n) {
       if (n >= 100000) return "$n";
@@ -242,4 +248,14 @@ class Duration implements Comparable<Duration> {
         sixDigits(inMicroseconds.remainder(MICROSECONDS_PER_SECOND));
     return "$inHours:$twoDigitMinutes:$twoDigitSeconds.$sixDigitUs";
   }
+
+  /**
+   * Returns whether this Duration is negative.

[Lasse Reichstein Nielsen, 2014/08/04 07:42:25]

Durations should never have been allowed to be negative! The name is just wrong
for that (I would have used "the duration of" in the description of "abs"!)

Since it is allowed, we'll have to define what it means, so add the paragraph
above to the documentation and add:
 *
 * A negative duration represents the difference from a later 
 * time to an earlier.

[srawlins, 2014/08/04 21:45:09]

Done.

+   */
+  bool isNegative() => _duration.isNegative;

[floitsch, 2014/08/01 13:07:03]

predicates are getters in Dart.

[Lasse Reichstein Nielsen, 2014/08/04 07:42:25]

Agree
  bool get isNegative => _duration < 0;

[srawlins, 2014/08/04 21:45:09]

Done.

[srawlins, 2014/08/04 21:45:09]

Done.

+
+  /**
+   * Returns a new Duration representing the absolute value of this Duration.

[Lasse Reichstein Nielsen, 2014/08/04 07:42:24]

Duration -> `Duration` (twice).

Also add:
 *
 * The returned `Duration` has the same length as this one, but is 
 * always positive.

[srawlins, 2014/08/04 21:45:09]

Done.

+   */
+  Duration abs() => new Duration(microseconds: _duration.abs());
 }