diff options
author | Heather Miller <heather.miller@epfl.ch> | 2011-08-20 19:52:30 +0000 |
---|---|---|
committer | Heather Miller <heather.miller@epfl.ch> | 2011-08-20 19:52:30 +0000 |
commit | e4559e4387796de1cdc7c03c2d69a375d14c8540 (patch) | |
tree | 773f156f57673b320dae7aa9114b2bb83508b61e /src/library | |
parent | 1bbf88a1fd32016335263c596b0d7b1947923714 (diff) | |
download | scala-e4559e4387796de1cdc7c03c2d69a375d14c8540.tar.gz scala-e4559e4387796de1cdc7c03c2d69a375d14c8540.tar.bz2 scala-e4559e4387796de1cdc7c03c2d69a375d14c8540.zip |
Improves documentation of scala.Predef.
Diffstat (limited to 'src/library')
-rw-r--r-- | src/library/scala/Predef.scala | 64 |
1 files changed, 61 insertions, 3 deletions
diff --git a/src/library/scala/Predef.scala b/src/library/scala/Predef.scala index 124858273d..54111dceba 100644 --- a/src/library/scala/Predef.scala +++ b/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] |