Deleted SourcelessComments.

Nothing and Null with improved documentation of their particulars
and convinced scaladoc to parse them without leaving scalac
institutionalized. Now rather than seeing our hardcoded documentation
strings bitrot in a shadowy flight from classes which do not exist, we
are championing the cause of the innocent and powerless. Nothing and
Null aren't above the law!

So now any responsible party can fire up their text editor and go to
town on Nothing.scala. As I'm sure they will. Review by malayeri.

5 files changed, 277 insertions, 0 deletions

diff --git a/src/library-aux/README b/src/library-aux/README
new file mode 100644
index 0000000000..e6dcd29277
--- /dev/null
+++ b/src/library-aux/README
@@ -0,0 +1,3 @@
+Source files under this directory cannot be compiled by normal means.
+
+They exist for bootstrapping and documentation purposes.
\ No newline at end of file
diff --git a/src/library-aux/scala/Any.scala b/src/library-aux/scala/Any.scala
new file mode 100644
index 0000000000..a97e5f050b
--- /dev/null
+++ b/src/library-aux/scala/Any.scala
@@ -0,0 +1,105 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2002-2010, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+package scala
+
+/** Class `Any` is the root of the Scala class hierarchy.  Every class in a Scala
+ *  execution environment inherits directly or indirectly from this class.
+ */
+abstract class Any {
+  /** Compares the receiver object (`this`) with the argument object (`that`) for equivalence.
+   *
+   *  The default implementations of this method is an [[http://en.wikipedia.org/wiki/Equivalence_relation equivalence relation]]:
+   *
+   *  - It is reflexive: for any instance `x` of type `Any`, `x.equals(x)` should return `true`.
+   *  - It is symmetric: for any instances `x` and `y` of type `Any`, `x.equals(y)` should return `true` if and
+   *    only if `y.equals(x)` returns `true`.
+   *  - It is transitive: for any instances `x`, `y`, and `z` of type `AnyRef` if `x.equals(y)` returns `true` and
+   *    `y.equals(z)` returns `true`, then `x.equals(z)` should return `true`.
+   *
+   *  If you override this method, you should verify that your implementation remains an equivalence relation.
+   *  Additionally, when overriding this method it is usually necessary to override `hashCode` to ensure that
+   *  objects which are "equal" (`o1.equals(o2)` returns `true`) hash to the same [[scala.Int]].
+   *  (`o1.hashCode.equals(o2.hashCode)`).
+   *
+   *  @param  that    the object to compare against this object for equality.
+   *  @return         `true` if the receiver object is equivalent to the argument; `false` otherwise.
+   */
+  def equals(that: Any): Boolean
+
+  /** Calculate a hash code value for the object.
+   *
+   *  The default hashing algorithm is platform dependent.
+   *
+   *  Note that it is allowed for two objects to have identical hash codes (`o1.hashCode.equals(o2.hashCode)`) yet
+   *  not be equal (`o1.equals(o2)` returns `false`).  A degenerate implementation could always return `0`.
+   *  However, it is required that if two objects are equal (`o1.equals(o2)` returns `true`) that they have
+   *  identical hash codes (`o1.hashCode.equals(o2.hashCode)`).  Therefore, when overriding this method, be sure
+   *  to verify that the behavior is consistent with the `equals` method.
+   *
+   *  @return   the hash code value for this object.
+   */
+  def hashCode: Int
+
+  /** Returns a string representation of the object.
+   *
+   *  The default representation is platform dependent.
+   *
+   *  @return a string representation of the object.
+   */
+  def toString: String
+
+  /** Test two objects for equality.
+   *
+   *  @param  that  the object to compare against this object for equality.
+   *  @return       `true` if the receiver object is equivalent to the argument; `false` otherwise.
+   */
+  final def ==(that: Any): Boolean = this equals that
+
+  /** Test two objects for inequality.
+   *
+   *  @param  that  the object to compare against this object for equality.
+   *  @return       `true` if !(this == that), false otherwise.
+   */
+  final def != (that: Any): Boolean = !(this == that)
+
+  /** Equivalent to `x.hashCode` except for boxed numeric types.
+   *  For numerics, it returns a hash value which is consistent
+   *  with value equality: if two value type instances compare
+   *  as true, then ## will produce the same hash value for each
+   *  of them.
+   *
+   *  @return   a hash value consistent with ==
+   */
+  final def ## : Int = sys.error("##")
+
+  /** Test whether the dynamic type of the receiver object is `T0`.
+   *
+   *  Note that the result of the test is modulo Scala's erasure semantics.
+   *  Therefore the expression `1.isInstanceOf[String]` will return `false`, while the
+   *  expression `List(1).isInstanceOf[List[String]]` will return `true`.
+   *  In the latter example, because the type argument is erased as part of compilation it is
+   *  not possible to check whether the contents of the list are of the specified type.
+   *
+   *  @return `true` if the receiver object is an instance of erasure of type `T0`; `false` otherwise.
+   */
+  def isInstanceOf[T0]: Boolean = sys.error("isInstanceOf")
+
+  /** Cast the receiver object to be of type `T0`.
+   *
+   *  Note that the success of a cast at runtime is modulo Scala's erasure semantics.
+   *  Therefore the expression `1.asInstanceOf[String]` will throw a `ClassCastException` at
+   *  runtime, while the expression `List(1).asInstanceOf[List[String]]` will not.
+   *  In the latter example, because the type argument is erased as part of compilation it is
+   *  not possible to check whether the contents of the list are of the requested type.
+   *
+   *  @throws ClassCastException if the receiver object is not an instance of the erasure of type `T0`.
+   *  @return the receiver object.
+   */
+  def asInstanceOf[T0]: T0 = sys.error("asInstanceOf")
+}
diff --git a/src/library-aux/scala/AnyRef.scala b/src/library-aux/scala/AnyRef.scala
new file mode 100644
index 0000000000..6792ba68b7
--- /dev/null
+++ b/src/library-aux/scala/AnyRef.scala
@@ -0,0 +1,129 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2002-2010, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+package scala
+
+/** Class `AnyRef` is the root class of all ''reference types''.
+ *  All types except the value types descend from this class.
+ */
+trait AnyRef extends Any {
+
+  /** The equality method for reference types.  See equals in [[scala.Any]].
+   *
+   *  @param  that    the object to compare against this object for equality.
+   *  @return         `true` if the receiver object is equivalent to the argument; `false` otherwise.
+   */
+  def equals(that: Any): Boolean = this eq that
+
+  /** The hashCode method for reference types.  See hashCode in [[scala.Any]].
+   *
+   *  @return   the hash code value for this object.
+   */
+  def hashCode: Int = sys.error("hashCode")
+
+  /** Creates a String representation of this object.  The default
+   *  representation is platform dependent.  On the java platform it
+   *  is the concatenation of the class name, "@", and the object's
+   *  hashcode in hexadecimal.
+   *
+   *  @return     a String representation of the object.
+   */
+  def toString: String = sys.error("toString")
+
+  /** Executes the code in `body` with an exclusive lock on `this`.
+   *
+   *  @param    body    the code to execute
+   *  @return           the result of `body`
+   */
+  def synchronized[T](body: => T): T
+
+  /** Tests whether the argument (`arg0`) is a reference to the receiver object (`this`).
+   *
+   *  The `eq` method implements an [[http://en.wikipedia.org/wiki/Equivalence_relation equivalence relation]] on
+   *  non-null instances of `AnyRef`, and has three additional properties:
+   *
+   *   - It is consistent: for any non-null instances `x` and `y` of type `AnyRef`, multiple invocations of
+   *     `x.eq(y)` consistently returns `true` or consistently returns `false`.
+   *   - For any non-null instance `x` of type `AnyRef`, `x.eq(null)` and `null.eq(x)` returns `false`.
+   *   - `null.eq(null)` returns `true`.
+   *
+   *  When overriding the `equals` or `hashCode` methods, it is important to ensure that their behavior is
+   *  consistent with reference equality.  Therefore, if two objects are references to each other (`o1 eq o2`), they
+   *  should be equal to each other (`o1 == o2`) and they should hash to the same value (`o1.hashCode == o2.hashCode`).
+   *
+   *  @param  that    the object to compare against this object for reference equality.
+   *  @return         `true` if the argument is a reference to the receiver object; `false` otherwise.
+   */
+  final def eq(that: AnyRef): Boolean = sys.error("eq")
+
+  /** Equivalent to `!(this eq that)`.
+   *
+   *  @param  that    the object to compare against this object for reference equality.
+   *  @return         `true` if the argument is not a reference to the receiver object; `false` otherwise.
+   */
+  final def ne(that: AnyRef): Boolean = !(this eq that)
+
+  /** The expression `x == that` is equivalent to `if (x eq null) that eq null else x.equals(that)`.
+   *
+   *  @param    arg0  the object to compare against this object for equality.
+   *  @return         `true` if the receiver object is equivalent to the argument; `false` otherwise.
+   */
+  final def ==(that: AnyRef): Boolean =
+    if (this eq null) that eq null
+    else this equals that
+
+  /** Create a copy of the receiver object.
+   *
+   *  The default implementation of the `clone` method is platform dependent.
+   *
+   *  @note   not specified by SLS as a member of AnyRef
+   *  @return a copy of the receiver object.
+   */
+  protected def clone(): AnyRef
+
+  /** Called by the garbage collector on the receiver object when there
+   *  are no more references to the object.
+   *
+   *  The details of when and if the `finalize` method is invoked, as
+   *  well as the interaction between `finalize` and non-local returns
+   *  and exceptions, are all platform dependent.
+   *
+   *  @note   not specified by SLS as a member of AnyRef
+   */
+  protected def finalize(): Unit
+
+  /** A representation that corresponds to the dynamic class of the receiver object.
+   *
+   *  The nature of the representation is platform dependent.
+   *
+   *  @note   not specified by SLS as a member of AnyRef
+   *  @return a representation that corresponds to the dynamic class of the receiver object.
+   */
+  def getClass(): Class[_]
+
+  /** Wakes up a single thread that is waiting on the receiver object's monitor.
+   *
+   *  @note   not specified by SLS as a member of AnyRef
+   */
+  def notify(): Unit
+
+  /** Wakes up all threads that are waiting on the receiver object's monitor.
+   *
+   *  @note   not specified by SLS as a member of AnyRef
+   */
+  def notifyAll(): Unit
+
+  /** Causes the current Thread to wait until another Thread invokes
+   *  the notify() or notifyAll() methods.
+   *
+   *  @note   not specified by SLS as a member of AnyRef
+   */
+  def wait (): Unit
+  def wait (timeout: Long, nanos: Int): Unit
+  def wait (timeout: Long): Unit
+}
diff --git a/src/library-aux/scala/Nothing.scala b/src/library-aux/scala/Nothing.scala
new file mode 100644
index 0000000000..eed6066039
--- /dev/null
+++ b/src/library-aux/scala/Nothing.scala
@@ -0,0 +1,23 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2002-2010, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+package scala
+
+/** `Nothing` is - together with [[scala.Null]] - at the bottom of Scala's type hierarchy.
+ *
+ *  `Nothing` is a subtype of every other type (including [[scala.Null]]); there exist
+ *  ''no instances'' of this type.  Although type `Nothing` is uninhabited, it is
+ *  nevertheless useful in several ways.  For instance, the Scala library defines a value
+ *  [[scala.collection.immutable.Nil]] of type `List[Nothing]`. Because lists are covariant in Scala,
+ *  this makes [[scala.collection.immutable.Nil]] an instance of `List[T]`, for any element of type `T`.
+ *
+ *  Another usage for Nothing is the return type for methods which never return normally.
+ *  One example is method error in [[scala.sys]], which always throws an exception.
+ */
+sealed trait Nothing
+
diff --git a/src/library-aux/scala/Null.scala b/src/library-aux/scala/Null.scala
new file mode 100644
index 0000000000..7455e78ae7
--- /dev/null
+++ b/src/library-aux/scala/Null.scala
@@ -0,0 +1,17 @@
+/*                     __                                               *\
+**     ________ ___   / /  ___     Scala API                            **
+**    / __/ __// _ | / /  / _ |    (c) 2002-2010, LAMP/EPFL             **
+**  __\ \/ /__/ __ |/ /__/ __ |    http://scala-lang.org/               **
+** /____/\___/_/ |_/____/_/ | |                                         **
+**                          |/                                          **
+\*                                                                      */
+
+package scala
+
+/** `Null` is - together with [[scala.Nothing]] - at the bottom of the Scala type hierarchy.
+ *
+ *  `Null` is a subtype of all reference types; its only instance is the `null` reference.
+ *  Since `Null` is not a subtype of value types, `null` is not a member of any such type.  For instance,
+ *  it is not possible to assign `null` to a variable of type [[scala.Int]].
+ */
+sealed trait Null