From bb30761427b8dffea0a1d455fd10e4e86447076a Mon Sep 17 00:00:00 2001 From: michelou Date: Mon, 13 Nov 2006 15:13:39 +0000 Subject: updated scaladoc comments in scala/Iterator.scala --- .../scala/tools/nsc/doc/DocGenerator.scala | 3 +- src/library/scala/Iterator.scala | 163 +++++++++++++-------- src/manual/scala/man1/scaladoc.scala | 2 +- 3 files changed, 105 insertions(+), 63 deletions(-) diff --git a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala index 8b1bcb17b1..98145bbf34 100644 --- a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala +++ b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala @@ -1098,6 +1098,7 @@ abstract class DocGenerator extends Models { case "deprecated" => "Deprecated" case "exception" => "Throws" case "param" => "Parameters" + case "pre" => "Precondition" case "return" => "Returns" case "see" => "See Also" case "since" => "Since" @@ -1110,7 +1111,7 @@ abstract class DocGenerator extends Models { // patterns for standard tags with 1 and 2 arguments private val pat1 = Pattern.compile( - "[ \t]*@(author|deprecated|return|see|since|todo|version)[ \t]*(.*)") + "[ \t]*@(author|deprecated|pre|return|see|since|todo|version)[ \t]*(.*)") private val pat2 = Pattern.compile( "[ \t]*@(exception|param|throws)[ \t]+(\\p{Graph}*)[ \t]*(.*)") diff --git a/src/library/scala/Iterator.scala b/src/library/scala/Iterator.scala index a7dd7c6aad..ad71b86232 100644 --- a/src/library/scala/Iterator.scala +++ b/src/library/scala/Iterator.scala @@ -25,9 +25,13 @@ object Iterator { def empty[a] = new Iterator[a] { def hasNext: Boolean = false - def next: a = throw new NoSuchElementException("next on empty iterator") + def next: a = throw new NoSuchElementException("next on empty iterator") } + /** + * @param x the element + * @return the iterator with one single element + */ def single[a](x: a) = new Iterator[a] { private var hasnext = true def hasNext: Boolean = hasnext @@ -38,14 +42,18 @@ object Iterator { def fromValues[a](xs: a*) = xs.elements + /** + * @param xs the array of elements + * @return the iterator on xs. + */ def fromArray[a](xs: Array[a]): Iterator[a] = fromArray(xs, 0, xs.length) /** - * @param xs ... + * @param xs the array of elements * @param start ... * @param length ... - * @return ... + * @return ... */ def fromArray[a](xs: Array[a], start: Int, length: Int): Iterator[a] = new BufferedIterator[a] { @@ -58,6 +66,10 @@ object Iterator { else throw new NoSuchElementException("head on empty iterator") } + /** + * @param str the given string + * @return the iterator on str + */ def fromString(str: String): Iterator[Char] = new BufferedIterator[Char] { private var i = 0 @@ -67,24 +79,30 @@ object Iterator { def head = str charAt i } - def fromProduct(n:Product): Iterator[Any] = new Iterator[Any] { + /** + * @param n the product arity + * @return the iterator on Product<n>. + */ + def fromProduct(n: Product): Iterator[Any] = new Iterator[Any] { private var c: Int = 0 private val cmax = n.arity def hasNext = c < cmax def next = { val a = n element c; c = c + 1; a } } - /** deprecated */ - def fromCaseClass(n:Product) = fromProduct(n) + /** + * @deprecated use class Product<n> instead. + */ + def fromCaseClass(n: Product) = fromProduct(n) /** Create an iterator with elements * en+1 = en + 1 * where e0 = lo * and ei < end. * - * @param lo the start value of the iterator + * @param lo the start value of the iterator * @param end the end value of the iterator - * @return the iterator with values in range [lo;end). + * @return the iterator with values in range [lo;end). */ def range(lo: Int, end: Int): Iterator[Int] = range(lo, end, 1) @@ -94,10 +112,10 @@ object Iterator { * where e0 = lo * and ei < end. * - * @param lo the start value of the iterator - * @param end the end value of the iterator + * @param lo the start value of the iterator + * @param end the end value of the iterator * @param step the increment value of the iterator (must be positive or negative) - * @return the iterator with values in range [lo;end). + * @return the iterator with values in range [lo;end). */ def range(lo: Int, end: Int, step: Int): Iterator[Int] = { assert(step != 0) @@ -118,10 +136,10 @@ object Iterator { * where e0 = lo * and ei < end. * - * @param lo the start value of the iterator - * @param end the end value of the iterator + * @param lo the start value of the iterator + * @param end the end value of the iterator * @param step the increment function of the iterator - * @return the iterator with values in range [lo;end). + * @return the iterator with values in range [lo;end). */ def range(lo: Int, end: Int, step: Int => Int): Iterator[Int] = new BufferedIterator[Int] { @@ -140,7 +158,7 @@ object Iterator { * where e0 = lo. * * @param lo the start value of the iterator - * @return the iterator starting at value lo. + * @return the iterator starting at value lo. */ def from(lo: Int): Iterator[Int] = from(lo, 1) @@ -149,9 +167,9 @@ object Iterator { * en+1 = en + step * where e0 = lo. * - * @param lo the start value of the iterator + * @param lo the start value of the iterator * @param step the increment value of the iterator - * @return the iterator starting at value lo. + * @return the iterator starting at value lo. */ def from(lo: Int, step: Int): Iterator[Int] = new BufferedIterator[Int] { @@ -165,9 +183,9 @@ object Iterator { * en+1 = step(en) * where e0 = lo. * - * @param lo the start value of the iterator + * @param lo the start value of the iterator * @param step the increment function of the iterator - * @return the iterator starting at value lo. + * @return the iterator starting at value lo. */ def from(lo: Int, step: Int => Int): Iterator[Int] = new BufferedIterator[Int] { @@ -184,8 +202,7 @@ object Iterator { * if there is a next element available, and a next method * which returns the next element and discards it from the iterator. * - * @author Martin Odersky - * @author Matthias Zenger + * @author Martin Odersky, Matthias Zenger * @version 1.2, 15/03/2004 */ trait Iterator[+A] { @@ -200,6 +217,9 @@ trait Iterator[+A] { /** Returns a new iterator that iterates only over the first n * elements. + * + * @param n the first n elements of the iterator + * @return the new iterator */ def take(n: Int) = new Iterator[A] { var remaining = n @@ -234,8 +254,9 @@ trait Iterator[+A] { * this iterator, then concatenates the results. * * @param f the function to apply on each element. - * @return an iterator over f(a0), ... , f(an) if this iterator - * yields the elements a0, ..., an. + * @return an iterator over f(a0), ... , + * f(an) if this iterator yields the + * elements a0, ..., an. */ def flatMap[B](f: A => Iterator[B]): Iterator[B] = new Iterator[B] { private var cur: Iterator[B] = Iterator.empty @@ -273,7 +294,7 @@ trait Iterator[+A] { def hasNext: Boolean = { skip; ahead || hasMore } def next: A = if (hasNext) { ahead = false; hd } - else throw new NoSuchElementException("next on empty iterator"); + else throw new NoSuchElementException("next on empty iterator") def head: A = { skip; hd } } @@ -281,25 +302,26 @@ trait Iterator[+A] { * that by associating each element of the former with * the element at the same position in the latter. * - * @param that must have the same number of elements as this - * iterator. - * @return an iterator yielding (a0,b0), ..., (an,bn) where - * ai are the elements from this iterator and - * bi are the elements from iterator that. + * @param that list that must have the same number of + * elements as this iterator. + * @return an iterator yielding (a0,b0), ..., + * (an,bn) where + * ai are the elements from this iterator + * and bi are the elements from iterator + * that. */ def zip[B](that: Iterator[B]) = new Iterator[Pair[A, B]] { def hasNext = Iterator.this.hasNext && that.hasNext def next = Pair(Iterator.this.next, that.next) } - /** Return an iterator that pairs each element of this iterator * with its index, counting from 0. * - * @param start the index of the first element - * - * @return an iterator yielding (a0,0), (a0,1)... - * where ai are the elements from this iterator. + * @param start the index of the first element. + * @return an iterator yielding (a0,0), + * (a0,1)... where ai + * are the elements from this iterator. */ def zipWithIndex = new Iterator[Pair[A, int]] { var idx = 0 @@ -316,14 +338,15 @@ trait Iterator[+A] { * * @param f a function that is applied to every element. */ - def foreach(f: A => Unit): Unit = while (hasNext) { f(next) } + def foreach(f: A => Unit): Unit = while (hasNext) f(next) /** Apply a predicate p to all elements of this - * iterable object and return true, iff the predicate yields - * true for all elements. + * iterable object and return true iff the predicate yields + * true for all elements. * - * @param p the predicate - * @returns true, iff the predicate yields true for all elements. + * @param p the predicate + * @return true iff the predicate yields true + * for all elements. */ def forall(p: A => Boolean): Boolean = { var res = true @@ -333,10 +356,11 @@ trait Iterator[+A] { /** Apply a predicate p to all elements of this * iterable object and return true, iff there is at least one - * element for which p yields true. + * element for which p yields true. * - * @param p the predicate - * @returns true, iff the predicate yields true for at least one element. + * @param p the predicate + * @return true iff the predicate yields true + * for at least one element. */ def exists(p: A => Boolean): Boolean = { var res = false @@ -347,8 +371,8 @@ trait Iterator[+A] { /** Tests if the given value elem is a member of this list. * * @param elem element whose membership has to be tested. - * @return True iff there is an element of this list which is - * equal (w.r.t. ==) to elem. + * @return true iff there is an element of this list which + * is equal (w.r.t. ==) to elem. */ def contains(elem: Any): Boolean = exists { x => x == elem } @@ -356,14 +380,14 @@ trait Iterator[+A] { * predicate, if any. * * @param p the predicate - * @return the first element in the iterable object satisfying p, - * or None if none exists. + * @return the first element in the iterable object satisfying + * p, or None if none exists. */ def find(p: A => Boolean): Option[A] = { var res: Option[A] = None while (res.isEmpty && hasNext) { val e = next - if (p(e)) res = Some(e); + if (p(e)) res = Some(e) } res } @@ -371,8 +395,10 @@ trait Iterator[+A] { /** Combines the elements of this list together using the binary * operator op, from left to right, and starting with * the value z. - * @return op(... (op(op(z,a0),a1) ...), an) if the list - * is List(a0, a1, ..., an). + * + * @return op(... (op(op(z,a0),a1) ...), + * an) if the list is + * List(a0, a1, ..., an). */ def foldLeft[B](z: B)(op: (B, A) => B): B = { var acc = z @@ -383,23 +409,36 @@ trait Iterator[+A] { /** Combines the elements of this list together using the binary * operator op, from rigth to left, and starting with * the value z. - * @return a0 op (... op (an op z)...) if the list - * is [a0, a1, ..., an]. + * + * @return a0 op (... op (an op z)...) + * if the list is List(a0, a1, ..., + * an). */ def foldRight[B](z: B)(op: (A, B) => B): B = { - def fold(z: B): B = - if (hasNext) op(next, fold(z)) else z; + def fold(z: B): B = if (hasNext) op(next, fold(z)) else z fold(z) } /** Similar to foldLeft but can be used as * an operator with the order of list and zero arguments reversed. - * That is, z /: xs is the same as xs foldLeft z + * That is, z /: xs is the same as xs foldLeft z. + * + * @param z the left argument of the first application of f + * (evaluation occurs from left to right). + * @param f the applied function. + * @return the result value + * @see foldLeft. */ def /:[B](z: B)(f: (B, A) => B): B = foldLeft(z)(f) /** An alias for foldRight. - * That is, xs :\ z is the same as xs foldRight z + * That is, xs :\ z is the same as xs foldRight z. + * + * @param z the right argument of the first application of f + * (evaluation occurs from right to left). + * @param f the applied function. + * @return the result value. + * @see foldRight. */ def :\[B](z: B)(f: (A, B) => B): B = foldRight(z)(f) @@ -410,7 +449,7 @@ trait Iterator[+A] { private var ahead: Boolean = false def head: A = { if (!ahead) { - hd = Iterator.this.next; + hd = Iterator.this.next ahead = true } hd @@ -431,6 +470,8 @@ trait Iterator[+A] { /** Creates two new iterators that both iterate over the same elements * than this iterator (in the same order). + * + * @return a pair of iterators */ def duplicate: Pair[Iterator[A], Iterator[A]] = { var xs: List[A] = Nil @@ -468,11 +509,11 @@ trait Iterator[+A] { /** Fills the given array xs with the elements of * this sequence starting at position start. * - * @param xs the array to fill. - * @param start starting index. - * @return the given array xs filled with the elements of - * this iterator. - * @pre The array must be large enough to hold all elements. + * @param xs the array to fill. + * @param start the starting index. + * @return the given array xs filled with the elements + * of this iterator. + * @pre the array must be large enough to hold all elements. */ def copyToArray[B >: A](xs: Array[B], start: Int): Array[B] = { var i = start diff --git a/src/manual/scala/man1/scaladoc.scala b/src/manual/scala/man1/scaladoc.scala index 712e4f31cc..1b826dd16e 100644 --- a/src/manual/scala/man1/scaladoc.scala +++ b/src/manual/scala/man1/scaladoc.scala @@ -50,7 +50,7 @@ object scaladoc extends Command { BulletList( Mono("@author"), Mono("@deprecated"), Mono("@exception") & " (two arguments)", - Mono("@param") & " (two arguments)", + Mono("@param") & " (two arguments)", Mono("@pre"), Mono("@return"), Mono("@see"), Mono("@since"), Mono("@throws") & " (two arguments)", Mono("@todo"), Mono("@version")), -- cgit v1.2.3