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

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

BUG= https://code.google.com/p/dart/issues/detail?id=9789
R=lrn@google.com

Committed: https://code.google.com/p/dart/source/detail?r=38973

[srawlins, 2014-08-01 02:05:51]

Hi Florian, you appear to be the last one to touch duration.dart, in 2012 :)
would you mind reviewing?

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

I'm on vacation right now. Reassigning to Lasse.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart
File sdk/lib/core/duration.dart (right):

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:255: bool isNegative() => _duration.isNegative;
predicates are getters in Dart.

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

lgtm

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart
File sdk/lib/core/duration.dart (right):

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:8: * A span of time, such as 27 days, 4 hours, 12
minutes, and 3 seconds.
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.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:213: * This function returns a negative integer if
this Duration is smaller than
"This function returns" -> "Returns"
Duration -> `Duration`
smaller -> shorter

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:214: * [other], or a positive integer if it is
greater.
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`.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:219: * Returns a string representation of this
Duration with hours, minutes,
Make a short first line, e.g.:

"Returns a string representation of this `Duration`.

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

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:253: * Returns whether this Duration is negative.
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.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:255: bool isNegative() => _duration.isNegative;
Agree
  bool get isNegative => _duration < 0;

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:258: * Returns a new Duration representing the
absolute value of this Duration.
Duration -> `Duration` (twice).

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

[Sean Eagan, 2014-08-04 18:07:37]

On 2014/08/01 02:05:51, srawlins wrote:
> Hi Florian, you appear to be the last one to touch duration.dart, in 2012 :)
> would you mind reviewing?

Unary minus would make sense as part of this CL as well:

  Duration operator -() => new Duration(microseconds: -_duration);

[srawlins, 2014-08-04 21:45:10]

Thanks Lasse and Sean!

I added unary- and all of lrn@'s doc tweaks. It looks very nice now.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart
File sdk/lib/core/duration.dart (right):

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:8: * A span of time, such as 27 days, 4 hours, 12
minutes, and 3 seconds.
On 2014/08/04 07:42:25, Lasse Reichstein Nielsen wrote:
> 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.
>  

Done.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:213: * This function returns a negative integer if
this Duration is smaller than
On 2014/08/04 07:42:25, Lasse Reichstein Nielsen wrote:
> "This function returns" -> "Returns"
> Duration -> `Duration`
> smaller -> shorter

Done.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:214: * [other], or a positive integer if it is
greater.
On 2014/08/04 07:42:25, Lasse Reichstein Nielsen wrote:
> 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`.

Done.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:219: * Returns a string representation of this
Duration with hours, minutes,
On 2014/08/04 07:42:25, Lasse Reichstein Nielsen wrote:
> Make a short first line, e.g.:
> 
> "Returns a string representation of this `Duration`.
> 
> Returns a string with hours, minutes, ..."

Done.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:253: * Returns whether this Duration is negative.
On 2014/08/04 07:42:25, Lasse Reichstein Nielsen wrote:
> 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.
> 
> 
> 

Done.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:255: bool isNegative() => _duration.isNegative;
On 2014/08/01 13:07:03, floitsch wrote:
> predicates are getters in Dart.

Done.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:255: bool isNegative() => _duration.isNegative;
On 2014/08/04 07:42:25, Lasse Reichstein Nielsen wrote:
> Agree
>   bool get isNegative => _duration < 0;

Done.

https://codereview.chromium.org/431263004/diff/1/sdk/lib/core/duration.dart#n...
sdk/lib/core/duration.dart:258: * Returns a new Duration representing the
absolute value of this Duration.
On 2014/08/04 07:42:24, Lasse Reichstein Nielsen wrote:
> Duration -> `Duration` (twice).
> 
> Also add:
>  *
>  * The returned `Duration` has the same length as this one, but is 
>  * always positive.

Done.

[Lasse Reichstein Nielsen, 2014-08-05 07:57:51]

Still LGTM

[Lasse Reichstein Nielsen, 2014-08-07 09:40:46]

Committed patchset #2 manually as 38973 (presubmit successful).