Added fixnum package docs.

pkg/fixnum/lib/src/intx.dart

 // Copyright (c) 2012, 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 fixnum;
 
 /**
  * A fixed-precision integer.
  */
 abstract class IntX implements Comparable {
 
-  // Arithmetic operations.
+  /** Addition operator. */

[justinfagnani, 2013/08/14 17:06:51]

Q for Kathy I guess: Should we doc the operators if they do the unsurprising
thing? It seems like documenting an implementation of a method defined in
another class. In Java we don't do that unless there's specific behavior that
differs from the declaration.

[Chris Bracken, 2013/08/14 17:45:31]

Java doesn't provide operator overloads, but where it provides methods (e.g.
BigInteger) they're documented. In dart:core, int documents these.

[Kathy Walrath, 2013/08/14 17:55:28]

I'm against documenting the obvious. (The exception is examples; those can be
obvious, since they confirm that using this API really is as simple as it
seems.)

On 2013/08/14 17:06:51, justinfagnani wrote:

[Chris Bracken, 2013/08/14 18:13:58]

I think the real solution is for me to extend these docs slightly to cover
over/underflow behaviour and type promotion. Will do that in a follow-up CL.

   IntX operator +(other);
+
+  /** Subtraction operator. */
   IntX operator -(other);
-  // The unary '-' operator.  Note that -MIN_VALUE will be equal
-  // to MIN_VALUE due to overflow.
+
+  /**
+   * Negate operator.
+   *
+   * Note that `-MIN_VALUE` is equal to `MIN_VALUE` due to overflow.
+   */
   IntX operator -();
+
+  /** Multiplication operator. */
   IntX operator *(other);
+
+  /**
+   * Euclidean modulo operator.
+   *
+   * Returns the remainder of the euclidean division. The euclidean division
+   * of two integers `a` and `b` yields two integers `q` and `r` such that
+   * `a == b * q + r` and `0 <= r < a.abs()`.
+   */
   IntX operator %(other);
-  // Truncating division.
+
+  /** Truncating division operator. */
   IntX operator ~/(other);
+
+  /**
+   * Returns the remainder of the truncating division of this integer by
+   * [other].
+   */
   IntX remainder(other);
 
-  // Note: no / operator
+  /** Bitwise and operator. */
+  IntX operator &(other);
 
-  // Bit-operations.
-  IntX operator &(other);
+  /** Bitwise or operator. */
   IntX operator |(other);
+
+  /** Bitwise xor operator. */
   IntX operator ^(other);
+
+  /** Bitwise negate operator. */
   IntX operator ~();
+
+  /**
+   * Left bit-shift operator.
+   *
+   * Returns the result of shifting the bits of this integer by [shiftAmount]
+   * bits to the left. Low-order bits are filled with zeros.
+   */
   IntX operator <<(int shiftAmount);
+
+  /**
+   * Right bit-shift operator.
+   *
+   * Returns the result of shifting the bits of this integer by [shiftAmount]
+   * bits to the right. High-order bits are filled with zero in the case where
+   * this integer is positive, or one in the case where it is negative.
+   */
   IntX operator >>(int shiftAmount);
+
+  /**
+   * Unsigned right-shift operator.
+   *
+   * Returns the result of shifting the bits of this integer by [shiftAmount]
+   * bits to the right. High-order bits are filled with zeros.
+   */
   IntX shiftRightUnsigned(int shiftAmount);
 
-  // Relational operations, may be applied to IntX or int.
   int compareTo(Comparable other);

[Kathy Walrath, 2013/08/14 17:15:07]

Nothing interesting to say here?

[Chris Bracken, 2013/08/14 17:45:31]

compareTo() docs are picked up off Comparable. I could provide detail more
specific to intx & friends if useful.

[Kathy Walrath, 2013/08/14 17:55:28]

Only if it's useful.

On 2013/08/14 17:45:31, Chris Bracken wrote:

+
   bool operator ==(other);

[Kathy Walrath, 2013/08/14 17:15:07]

Can we say anything here? Do we really want the superclass to show through here?

[Chris Bracken, 2013/08/14 17:45:31]

Done.

+
+  /** Relational less than operator. */
   bool operator <(other);
+
+  /** Relational less than or equal to operator. */
   bool operator <=(other);
+
+  /** Relational greater than operator. */
   bool operator >(other);
+
+  /** Relational greater than or equal to operator. */
   bool operator >=(other);
 
-  // Testers.
+  /** Returns `true` if and only if this integer is even. */
   bool get isEven;
+
+  /**
+   * Returns `true` if and only if this integer is the maximum signed value
+   * that can be represented within its bit size.
+   */
   bool get isMaxValue;
+
+  /**
+   * Returns `true` if and only if this integer is the minimum signed value
+   * that can be represented within its bit size.
+   */
   bool get isMinValue;
+
+  /** Returns `true` if and only if this integer less than zero. */

[Kathy Walrath, 2013/08/14 17:15:07]

less -> is less

[Chris Bracken, 2013/08/14 17:45:31]

Done.

   bool get isNegative;
+
+  /** Returns `true` if and only if this integer is odd. */
   bool get isOdd;
+
+  /** Returns `true` if and only if this integer is zero. */
   bool get isZero;
 
   int get hashCode;
 
+  /** Returns the absolute value of this integer. */
   IntX abs();
 
   /**
-   * Returns the number of leading zeros in this [IntX] as an [int]
-   * between 0 and 64.
+   * Returns the number of high-order zeros in this integer's bit
+   * representation.
    */
   int numberOfLeadingZeros();
 
   /**
-   * Returns the number of trailing zeros in this [IntX] as an [int]
-   * between 0 and 64.
+   * Returns the number of low-order zeros in this integer's bit representation.
    */
   int numberOfTrailingZeros();
 
   /**
-   * Converts this [IntX] to a [List] of [int], starting with the least
+   * Returns a byte-sequence representation of this integer.
+   *
+   * Returns a [List] of [int], one per byte, starting with the least

[Kathy Walrath, 2013/08/14 17:15:07]

There's no need to link to the types, since you get that from the signature.
Maybe:

Returns a list of integers, one int per byte, ...
OR
Returns a List of int, ...

[Chris Bracken, 2013/08/14 17:45:31]

Done.

    * significant byte.
    */
   List<int> toBytes();
 
   /**
-   * Converts this [IntX] to an [int].  On some platforms, inputs with large
-   * absolute values (i.e., > 2^52) may lose some of their low bits.
+   * Returns the [int] representation of this integer.

[Kathy Walrath, 2013/08/14 17:15:07]

[int] -> int

[Chris Bracken, 2013/08/14 17:45:31]

Done.

+   *
+   * On some platforms, inputs with large absolute values (i.e., > 2^52) may
+   * lose some of their low-order bits.
    */
   int toInt();
 
   /**
-   * Converts an [IntX] to 32 bits.  Narrower values are sign extended and
-   * wider values have their high bits truncated.
+   * Returns an [Int32] representation of this integer.

[Kathy Walrath, 2013/08/14 17:15:07]

[Int32] -> Int32

[Chris Bracken, 2013/08/14 17:45:31]

Done.

+   *
+   * Narrower values are sign-extended and wider values have their high bits
+   * truncated.
    */
   Int32 toInt32();
 
-  /**
-   * Converts an [IntX] to 64 bits.
-   */
+  /** Returns an [Int64] representation of this integer. */

[Kathy Walrath, 2013/08/14 17:15:07]

[Int64] -> Int64

[Chris Bracken, 2013/08/14 17:45:31]

Done.

   Int64 toInt64();
 
-  /**
-   * Returns the value of this [IntX] as a decimal [String].
-   */
+  /** Returns a decimal [String] representation of this integer. */

[Kathy Walrath, 2013/08/14 17:15:07]

I had a hard time reading this at first. How about:

Returns a string representing the decimal value of this integer;
example: '13'.

[Chris Bracken, 2013/08/14 17:45:31]

Done.

   String toString();
 
-  /**
-   * Returns the value of this [IntX] as a hexadecimal [String].
-   */
+  /** Returns a hexadecimal [String] representation of this integer. */

[Kathy Walrath, 2013/08/14 17:15:07]

Maybe:

Returns a string representing the hexadecimal value of this integer; example:
'0xd'.

[Chris Bracken, 2013/08/14 17:45:31]

Done.

   String toHexString();
 
   /**
-   * Returns the value of this [IntX] as a [String] in the given radix.
-   * [radix] must be an integer between 2 and 16, inclusive.
+   * Returns a [String] representation of this integer in the given radix.

[Kathy Walrath, 2013/08/14 17:15:07]

Maybe:

Returns a string representing the value of this integer in the given radix.

[Chris Bracken, 2013/08/14 17:45:31]

Done.

+   *
+   * [radix] must be an integer in the range 2 .. 16, inclusive.
    */
   String toRadixString(int radix);
 }