diff options
author | michelou <michelou@epfl.ch> | 2006-11-12 20:03:16 +0000 |
---|---|---|
committer | michelou <michelou@epfl.ch> | 2006-11-12 20:03:16 +0000 |
commit | f165c87a43b9d99df14788e0ceb4f0277ec21f7b (patch) | |
tree | 606b2ebec5f2b1d3dc523db7243e51ae9018e53c /src | |
parent | 7faacc7b75bc40f788ded76b490d7f98b3ba1304 (diff) | |
download | scala-f165c87a43b9d99df14788e0ceb4f0277ec21f7b.tar.gz scala-f165c87a43b9d99df14788e0ceb4f0277ec21f7b.tar.bz2 scala-f165c87a43b9d99df14788e0ceb4f0277ec21f7b.zip |
improved scaladoc comments in List, collection....
improved scaladoc comments in List, collection.Map, etc.
Diffstat (limited to 'src')
-rw-r--r-- | src/compiler/scala/tools/nsc/doc/DocGenerator.scala | 4 | ||||
-rw-r--r-- | src/library/scala/List.scala | 90 | ||||
-rw-r--r-- | src/library/scala/collection/Map.scala | 33 | ||||
-rw-r--r-- | src/library/scala/collection/Set.scala | 30 |
4 files changed, 97 insertions, 60 deletions
diff --git a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala index 9216c2149e..72dab71d7f 100644 --- a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala +++ b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala @@ -1151,7 +1151,9 @@ abstract class DocGenerator extends Models { "Predef.NoSuchElementException" -> Pair(definitions.PredefModule, "NoSuchElementException") + "Predef.NullPointerException" -> - Pair(definitions.PredefModule, "NullPointerException") + Pair(definitions.PredefModule, "NullPointerException") + + "Predef.UnsupportedOperationException" -> + Pair(definitions.PredefModule, "UnsupportedOperationException") val body = buf.toString if (isShort) <span>{parse(body)}</span>; else <span><dl><dd>{parse(body)}</dd></dl><dl> diff --git a/src/library/scala/List.scala b/src/library/scala/List.scala index fcf6c1d680..912a2c2468 100644 --- a/src/library/scala/List.scala +++ b/src/library/scala/List.scala @@ -96,10 +96,11 @@ object List { /** Create a list by applying a function to successive integers. * * @param n the length of the resulting list - * @param maker the procedure which, given an integer n, returns the - * nth element of the resulting list, where n is in [0;n). - * @return the list obtained by applying the maker function to successive - * integers from 0 to n (exclusive). + * @param maker the procedure which, given an integer <code>n</code>, + * returns the nth element of the resulting list, where + * <code>n</code> is in interval <code>[0;n)</code>. + * @return the list obtained by applying the maker function to + * successive integers from 0 to n (exclusive). */ def tabulate[a](n: Int, maker: Int => a): List[a] = { val b = new ListBuffer[a] @@ -208,7 +209,7 @@ object List { /** Returns the given string as a list of characters. * * @param str the string to convert. - * @return the string as a list of characters. + * @return the string as a list of characters. */ def fromString(str: String): List[Char] = Iterator.fromString(str).toList @@ -216,7 +217,7 @@ object List { /** Returns the given list of characters as a string. * * @param xs the list to convert. - * @return the list in form of a string. + * @return the list in form of a string. */ def toString(xs: List[Char]): String = { val sb = new compat.StringBuilder() @@ -306,8 +307,10 @@ object List { * for all corresponding elements of the argument lists. * * @param p function to apply to each pair of elements. - * @return <code>n == 0 || (p(a0,b0) && ... && p(an,bn))]</code> - * if the lists are <code>[a0, ..., ak]</code>, <code>[b0, ..., bl]</code> + * @return <code>n == 0 || (p(a<sub>0</sub>,b<sub>0</sub>) && + * ... && p(a<sub>n</sub>,b<sub>n</sub>))]</code> + * if the lists are <code>[a<sub>0</sub>, ..., a<sub>k</sub>]</code>; + * <code>[b<sub>0</sub>, ..., b<sub>l</sub>]</code> * and <code>m = min(k,l)</code> */ def forall2[a,b](xs: List[a], ys: List[b])(f: (a, b) => boolean): boolean = { @@ -759,15 +762,22 @@ sealed abstract class List[+a] extends Seq[a] { Pair(btrue.toList, bfalse.toList) } - /** Sort the list according to the comparison function - * <code><(e1: a, e2: a) => Boolean</code>, - * which should be true iff e1 is smaller than e2. - * Note: The current implementation is inefficent for - * already sorted lists. + /** <p> + * Sort the list according to the comparison function + * <code><(e1: a, e2: a) => Boolean</code>, + * which should be true iff <code>e1</code> is smaller than + * <code>e2</code>. Example: + * </p> + * <pre>List("Tom", "John", "Bob").sort( + * (e1, e2) => (e1 compareTo e2) < 0)</pre> + * <p> + * Note: The current implementation is inefficent for + * already sorted lists. + * </p> * * @param lt the comparison function - * @return a list sorted according to the comparison function - * <code><(e1: a, e2: a) => Boolean</code>. + * @return a list sorted according to the comparison function + * <code><(e1: a, e2: a) => Boolean</code>. */ def sort(lt : (a,a) => Boolean): List[a] = { def sort_1(smaller: List[a], acc: List[a]): List[a] = @@ -835,7 +845,8 @@ sealed abstract class List[+a] extends Seq[a] { * in this list. * * @param p the test predicate. - * @return True iff all elements of this list satisfy the predicate <code>p</code>. + * @return <code>true</code> iff all elements of this list satisfy the + * predicate <code>p</code>. */ override def forall(p: a => Boolean): Boolean = { var these = this @@ -850,8 +861,8 @@ sealed abstract class List[+a] extends Seq[a] { * <code>p</code>. * * @param p the test predicate. - * @return true iff there exists an element in this list that satisfies - * the predicate <code>p</code>. + * @return <code>true</code> iff there exists an element in this list that + * satisfies the predicate <code>p</code>. */ override def exists(p: a => Boolean): Boolean = { var these = this @@ -891,8 +902,9 @@ sealed abstract class List[+a] extends Seq[a] { * function <code>f</code>, from left to right, and starting with * the value <code>z</code>. * - * @return <code>f(... (f(f(z, a0), a1) ...), an)</code> if the list - * is <code>[a0, a1, ..., an]</code>. + * @return <code>f(... (f(f(z, a<sub>0</sub>), a<sub>1</sub>) ...), + * a<sub>n</sub>)</code> if the list is + * <code>[a<sub>0</sub>, a<sub>1</sub>, ..., a<sub>n</sub>]</code>. */ override def foldLeft[b](z: b)(f: (b, a) => b): b = { var acc = z @@ -908,19 +920,27 @@ sealed abstract class List[+a] extends Seq[a] { * function <code>f</code>, from rigth to left, and starting with * the value <code>z</code>. * - * @return <code>f(a0, f(a1, f(..., f(an, z)...)))</code> if the list - * is <code>[a0, a1, ..., an]</code>. + * @return <code>f(a<sub>0</sub>, f(a<sub>1</sub>, f(..., f(a<sub>n</sub>, z)...)))</code> + * if the list is <code>[a<sub>0</sub>, a1, ..., an]</code>. */ override def foldRight[b](z: b)(f: (a, b) => b): b = this match { case Nil => z case x :: xs => f(x, xs.foldRight(z)(f)) } + /** + * @return ... + * @throws Predef.UnsupportedOperationException ... + */ def reduceLeft[b >: a](f: (b, b) => b): b = this match { case Nil => throw new UnsupportedOperationException("Nil.reduceLeft") case x :: xs => ((xs: List[b]) foldLeft (x: b))(f) } + /** + * @return ... + * @throws Predef.UnsupportedOperationException ... + */ def reduceRight[b >: a](f: (b, b) => b): b = this match { case Nil => throw new UnsupportedOperationException("Nil.reduceRight") case x :: Nil => x: b @@ -949,12 +969,9 @@ sealed abstract class List[+a] extends Seq[a] { } /** <p> - * Reverses the elements of this list. - * </p> - * <p> - * Example: + * Reverses the elements of this list. Example: * </p> - * <code>[1, 2, 3] reverse = [3, 2, 1]</code>. + * <pre>List(1, 2, 3) reverse = List(3, 2, 1)</pre> * * @return the elements of this list in reverse order. */ @@ -965,9 +982,12 @@ sealed abstract class List[+a] extends Seq[a] { * <code>that</code> by associating each element of the former with * the element at the same position in the latter. * - * @param that <code>that</code> must have the same length as the self list. - * @return <code>[(a0,b0), ..., (an,bn)]</code> when - * <code>[a0, ..., an] zip [b0, ..., bn]</code> is invoked. + * @param that list <code>that</code> must have the same length as the + * self list. + * @return <code>[(a<sub>0</sub>,b<sub>0</sub>), ..., + * (a<sub>n</sub>,b<sub>n</sub>)]</code> when + * <code>[a<sub>0</sub>, ..., a<sub>n</sub>] + * zip [b<sub>0</sub>, ..., b<sub>n</sub>]</code> is invoked. */ def zip[b](that: List[b]): List[Pair[a,b]] = { val b = new ListBuffer[Pair[a, b]] @@ -985,8 +1005,10 @@ sealed abstract class List[+a] extends Seq[a] { * with its index, counting from 0. * * @param start the index of the first element - * @return an iterator yielding <code>(a0,0), (a0,1)...</code> - * where <code>ai</code> are the elements from this iterator. + * @return an iterator yielding <code>(a<sub>0</sub>,0), + * (a<sub>0</sub>,1)...</code> + * where <code>a<sub>i</sub></code> are the elements from + * this iterator. */ def zipWithIndex = { val b = new ListBuffer[Pair[a,int]] @@ -1014,7 +1036,9 @@ sealed abstract class List[+a] extends Seq[a] { * @param thatElem element <code>thatElem</code> is used to fill up the * resulting list if <code>that</code> is shorter than * the self list - * @return <code>[(a0,b0), ..., (an,bn), (elem,bn+1), ..., (elem,bm)]</code> + * @return <code>[(a<sub>0</sub>,b<sub>0</sub>), ..., + * (a<sub>n</sub>,b<sub>n</sub>), (elem,b<sub>n+1</sub>), + * ..., (elem,b<sub>m</sub>)]</code> * when <code>[a0, ..., an] zip [b0, ..., bm]</code> is * invoked where <code>m > n</code>. */ diff --git a/src/library/scala/collection/Map.scala b/src/library/scala/collection/Map.scala index 842544b3a4..211158f047 100644 --- a/src/library/scala/collection/Map.scala +++ b/src/library/scala/collection/Map.scala @@ -16,10 +16,12 @@ package scala.collection /** This class defines the interface of collections that unambiguously map * keys to values (i.e. a key is mapped to at least one value). - * Class <code>Map</code> may only be used for - * accessing elements from map implementations. Two different extensions - * of class <code>Map</code> in the package <code>scala.collections.mutable</code> - * and <code>scala.collections.immutable</code> provide functionality for + * Class <code>Map</code> may only be used for accessing elements from map + * implementations. Two different extensions of class <code>Map</code> in + * the package <code><a href="mutable$content.html" target="contentFrame"> + * scala.collection.mutable</a></code> + * and <code><a href="immutable$content.html" target="contentFrame"> + * scala.collection.immutable</a></code> provide functionality for * adding new key/value mappings to a map. The class in the first package is * implemented by maps that are modified destructively, whereas the class in * the second package is used by functional map implementations that rely on @@ -41,14 +43,14 @@ trait Map[A, +B] extends AnyRef /** Check if this map maps <code>key</code> to a value and return the * value if it exists. * - * @param key the key of the mapping of interest - * @return the value of the mapping, if it exists + * @param key the key of the mapping of interest + * @return the value of the mapping, if it exists */ def get(key: A): Option[B] /** Is this an empty map? * - * @return true, iff the map is empty. + * @return <code>true</code> iff the map is empty. */ def isEmpty: Boolean = (size == 0) @@ -56,8 +58,8 @@ trait Map[A, +B] extends AnyRef * method throws an exception if there is no mapping from the given * key to a value. * - * @param key the key - * @return the value associated with the given key. + * @param key the key + * @return the value associated with the given key. */ def apply(key: A): B = get(key) match { case None => default(key) @@ -66,8 +68,8 @@ trait Map[A, +B] extends AnyRef /** Is the given key mapped to a value by this map? * - * @param key the key - * @return true, iff there is a mapping for key in this map + * @param key the key + * @return <code>true</code> iff there is a mapping for key in this map */ def contains(key: A): Boolean = get(key) match { case None => false @@ -76,8 +78,8 @@ trait Map[A, +B] extends AnyRef /** Does this map contain a mapping from the given key to a value? * - * @param key the key - * @return true, iff there is a mapping for key in this map + * @param key the key + * @return <code>true</code> iff there is a mapping for key in this map */ def isDefinedAt(key: A) = contains(key) @@ -105,7 +107,9 @@ trait Map[A, +B] extends AnyRef * contained in this map are also contained in the other map, * and vice versa. * - * @return true, iff both maps contain exactly the same mappings. + * @param that the other map + * @return <code>true</code> iff both maps contain exactly the + * same mappings. */ override def equals(that: Any): Boolean = that match { case other: Map[a, b] => @@ -140,6 +144,7 @@ trait Map[A, +B] extends AnyRef * but it might be overridden in subclasses. * * @param key ... + * @throws Predef.NoSuchElementException ... */ def default(key: A): B = throw new NoSuchElementException("key not found: " + key) diff --git a/src/library/scala/collection/Set.scala b/src/library/scala/collection/Set.scala index 107a1948d6..0fd60805af 100644 --- a/src/library/scala/collection/Set.scala +++ b/src/library/scala/collection/Set.scala @@ -15,8 +15,11 @@ package scala.collection /** This class defines the interface of collections that do not contain * duplicate elements. Class <code>Set</code> may only be used for * accessing elements from set implementations. Two different extensions - * of class <code>Set</code> in the package <code>scala.collections.mutable</code> - * and <code>scala.collections.immutable</code> provide functionality for + * of class <code>Set</code> in the package + * <code><a href="mutable$content.html" target="contentFrame"> + * scala.collection.mutable</a></code> and + * <code><a href="immutable$content.html" target="contentFrame"> + * scala.collection.immutable</a></code> provide functionality for * adding new elements to a set. The class in the first package is implemented * by sets the are modified destructively, whereas the class in the second * package is used by functional set implementations that rely on immutable @@ -35,29 +38,32 @@ trait Set[A] extends AnyRef with Function1[A, Boolean] with Iterable[A] { /** Checks if this set contains element <code>elem</code>. * - * @param elem the element to check for membership. - * @return true, iff <code>elem</code> is contained in this set. + * @param elem the element to check for membership. + * @return <code>true</code> iff <code>elem</code> is contained ini + * this set. */ def contains(elem: A): Boolean /** This method allows sets to be interpreted as predicates. * It returns true, iff this set contains element <code>elem</code>. * - * @param elem the element to check for membership. - * @return true, iff <code>elem</code> is contained in this set. + * @param elem the element to check for membership. + * @return <code>true</code> iff <code>elem</code> is contained in + * this set. */ def apply(elem: A): Boolean = contains(elem) /** Checks if this set is empty. * - * @return true, iff there is no element in the set. + * @return <code>true</code> iff there is no element in the set. */ def isEmpty: Boolean = (size == 0) /** Checks if this set is a subset of set <code>that</code>. * - * @param that another set. - * @return true, iff the other set is a superset of this set. + * @param that another set. + * @return <code>true</code> iff the other set is a superset of + * this set. */ def subsetOf(that: Set[A]): Boolean = forall(that.contains) @@ -65,9 +71,9 @@ trait Set[A] extends AnyRef with Function1[A, Boolean] with Iterable[A] { * other object is also a set which contains the same elements as * this set. * - * @param that the other object - * @return true, iff this set and the other set contain the same - * elements. + * @param that the other object + * @return <code>true</code> iff this set and the other set + * contain the same elements. */ override def equals(that: Any): Boolean = that match { case other: Set[a] => |