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. */
   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);
+
+  /**
+   * Returns `true` if and only if [other] is an int or IntX equal in
+   * value to this integer.
+   */
   bool operator ==(other);
+
+  /** 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 is less than zero. */
   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
-   * significant byte.
+   * Returns a byte-sequence representation of this integer.
+   *
+   * Returns a list of int, starting with the least 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.
+   *
+   * 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.
+   *
+   * 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. */
   Int64 toInt64();
 
   /**
-   * Returns the value of this [IntX] as a decimal [String].
+   * Returns a string representating the value of this integer in decimal

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

representating!!
->
representing

(though I like representating)

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

Whoops - missed a couple backspaces. Done.

+   * notation; example: `13`.

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

shouldn't this have quotation marks, since it's a string literal?

(we usually use single quotes, fwiw)

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

Done.

    */
   String toString();
 
   /**
-   * Returns the value of this [IntX] as a hexadecimal [String].
+   * Returns a string representing the value of this integer in hexadecimal
+   * notation; example: `0xd`.

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

quotation marks?

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

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 representing the value of this integer in the given radix.
+   *
+   * [radix] must be an integer in the range 2 .. 16, inclusive.
    */
   String toRadixString(int radix);
 }