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

sdk/lib/core/duration.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.core;
 
 /**
  * A span of time, such as 27 days, 4 hours, 12 minutes, and 3 seconds.

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

Add paragraph:
 * 
 * A `Duration` represents a difference from one point in time 
 * to another. 
 * The duration may be "negative" if the difference is from a 
 * later time to an earlier.
 

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

Done.

  *
  * To create a new Duration object, use this class's single constructor
  * giving the appropriate arguments:
  *
  *     Duration fastestMarathon = new Duration(hours:2, minutes:3, seconds:2);
  *
  * The Duration is the sum of all individual parts.
  * This means that individual parts can be larger than the next-bigger unit.
  * For example, [minutes] can be greater than 59.
  *
@@ skipping 182 matching lines @@
    * Returns `true` if this Duration is the same object as [other].
    */
   bool operator ==(other) {
     if (other is !Duration) return false;
     return _duration == other._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";
       if (n >= 10000) return "0$n";
       if (n >= 1000) return "00$n";
       if (n >= 100) return "000$n";
       if (n >= 10) return "0000$n";
       return "00000$n";
     }
     String twoDigits(int n) {
       if (n >= 10) return "$n";
       return "0$n";
     }
 
     if (inMicroseconds < 0) {
       Duration duration =
           new Duration(microseconds: -inMicroseconds);
       return "-$duration";
     }
     String twoDigitMinutes = twoDigits(inMinutes.remainder(MINUTES_PER_HOUR));
     String twoDigitSeconds = twoDigits(inSeconds.remainder(SECONDS_PER_MINUTE));
     String sixDigitUs =
         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());
 }