Improves documentation of scala.Predef. Contributed by Iain McGinniss during the Aug 20 Docspree. Review by phaller.

git-svn-id: http://lampsvn.epfl.ch/svn-repos/scala/scala/trunk@25530 5e8d7ff9-d8ef-0310-90f0-a4852d11357a

src/library/scala/Predef.scala

@@ -17,12 +17,70 @@ import annotation.elidable.ASSERTION
 
 /** The `Predef` object provides definitions that are accessible in all Scala
  *  compilation units without explicit qualification.
+ *
+ *  === Commonly Used Types === 
+ *  Predef provides type aliases for types which are commonly used, such as
+ *  the immutable collection types [[scala.collection.immutable.Map]], 
+ *  [[scala.collection.immutable.Set]], and the [[scala.collection.immutable.List]] 
+ *  constructors ([[scala.collection.immutable.::]] and 
+ *  [[scala.collection.immutable.Nil]]).
+ *  The types `Pair` (a [[scala.Tuple2]]) and `Triple` (a [[scala.Tuple3]]), with
+ *  simple constructors, are also provided.
+ *
+ *  === Console I/O ===
+ *  Predef provides a number of simple functions for console I/O, such as
+ *  `print`, `println`, `readLine`, `readInt`, etc. These functions are all
+ *  aliases of the functions provided by [[scala.Console]].
+ *
+ *  === Assertions ===
+ *
+ *  A set of `assert` functions are provided for use as a way to document
+ *  and dynamically check invariants in code. `assert` statements can be elided 
+ *  at runtime by providing the command line argument `-Xdisable-assertions` to 
+ *  the `scala` command.
+ *
+ *  Variants of `assert` intended for use with static analysis tools are also
+ *  provided: `assume`, `require` and `ensuring`. `require` and `ensuring` are
+ *  intended for use as a means of design-by-contract style specification
+ *  of pre- and post-conditions on functions, with the intention that these
+ *  specifications could be consumed by a static analysis tool. For instance,
+ *  
+ *  {{{
+ *  def addNaturals(nats: List[Int]): Int = {
+ *    require(nats forall (_ >= 0), "List contains negative numbers")
+ *    nats.foldLeft(0)(_ + _)
+ *  } ensuring(_ >= 0)
+ *  }}}
+ *
+ *  The declaration of `addNaturals` states that the list of integers passed should
+ *  only contain natural numbers (i.e. non-negative), and that the result returned
+ *  will also be natural. `require` is distinct from `assert` in that if the
+ *  condition fails, then the caller of the function is to blame rather than a
+ *  logical error having been made within `addNaturals` itself. `ensures` is a
+ *  form of `assert` that declares the guarantee the function is providing with
+ *  regards to it's return value.
+ *
+ *  === Implicit Conversions ===
+ *  A number of commonly applied implicit conversions are also defined here, and
+ *  in the parent type [[scala.LowPriorityImplicits]]. Implicit conversions
+ *  are provided for the "widening" of numeric values, for instance, converting a
+ *  Short value to a Long value as required, and to add additional higher-order 
+ *  functions to Array values. These are described in more detail in the documentation of [[scala.Array]].
  */
 object Predef extends LowPriorityImplicits {
-  /** Return the runtime representation of a class type.  This is a stub method.
-   *  The actual implementation is filled in by the compiler.
+  /** 
+   * Retrieve the runtime representation of a class type. `classOf[T]` is equivalent to
+   * the class literal `T.class` in Java.
+   *
+   * @example {{{
+   * val listClass = classOf[List[_]]
+   * // listClass is java.lang.Class[List[_]] = class scala.collection.immutable.List
+   * 
+   * val mapIntString = classOf[Map[Int,String]]
+   * // mapIntString is java.lang.Class[Map[Int,String]] = interface scala.collection.immutable.Map
+   * }}}
    */
-  def classOf[T]: Class[T] = null
+  def classOf[T]: Class[T] = null // This is a stub method. The actual implementation is filled in by the compiler.
   
   type String        = java.lang.String
   type Class[T]      = java.lang.Class[T]