Some great AnyVal class hierarchy documentation...

Some great AnyVal class hierarchy documentation from Iain McGinniss. No
Review.

1 files changed, 449 insertions, 3 deletions

diff --git a/src/library/scala/Long.scala b/src/library/scala/Long.scala
index 12b8a25b8a..2a2bc896ac 100644
--- a/src/library/scala/Long.scala
+++ b/src/library/scala/Long.scala
@@ -10,8 +10,9 @@
 
 package scala
 
-/** `Long` is a member of the value classes, those whose instances are
- *  not represented as objects by the underlying host system.
+/** `Long`, a 64-bit signed integer (equivalent to Java's `long` primitive type) is a
+ *  subtype of [[scala.AnyVal]], meaning that instances of `Long` are not
+ *  represented by an object in the underlying runtime system.
  *
  *  There is an implicit conversion from [[scala.Long]] => [[scala.runtime.RichLong]]
  *  which provides useful non-primitive operations.
@@ -25,123 +26,568 @@ final class Long extends AnyVal {
   def toFloat: Float = sys.error("stub")
   def toDouble: Double = sys.error("stub")
 
+  /**
+ * @return the bitwise negation of this value
+ * @example {{{
+ * ~5 == -6
+ * // in binary: ~00000101 ==
+ * //             11111010
+ * }}}
+ */
+  def unary_~ : Long = sys.error("stub")
+  /**
+ * @return this value, unmodified
+ */
   def unary_+ : Long = sys.error("stub")
+  /**
+ * @return the negation of this value
+ */
   def unary_- : Long = sys.error("stub")
-  def unary_~ : Long = sys.error("stub")
 
   def +(x: String): String = sys.error("stub")
 
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Int): Long = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Long): Long = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Int): Long = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Long): Long = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Int): Long = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Short): Long = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Char): Long = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Int): Long = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Short): Long = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Char): Long = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Int): Long = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Short): Long = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Char): Long = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Int): Long = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Short): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Char): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Int): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Long): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Float): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Short): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Char): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Int): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Long): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Float): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Short): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Char): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Int): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Long): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Float): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Short): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Char): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Int): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Long): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Float): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Short): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Char): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Int): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Long): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Float): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Double): Double = sys.error("stub")
 
   def getClass(): Class[Long] = sys.error("stub")