diff options
author | michelou <michelou@epfl.ch> | 2006-10-11 22:02:11 +0000 |
---|---|---|
committer | michelou <michelou@epfl.ch> | 2006-10-11 22:02:11 +0000 |
commit | 27de82558058e859d6ec884727d85bc08d972f16 (patch) | |
tree | 3026bce1b963c6b375db96459b87f815706eecf7 | |
parent | a094bf3c2e43d8d29aa676f301a5dff99b0355a2 (diff) | |
download | scala-27de82558058e859d6ec884727d85bc08d972f16.tar.gz scala-27de82558058e859d6ec884727d85bc08d972f16.tar.bz2 scala-27de82558058e859d6ec884727d85bc08d972f16.zip |
improved comments in scala/collection/*.scala
18 files changed, 260 insertions, 142 deletions
diff --git a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala index ce7287697f..5bf30e518e 100644 --- a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala +++ b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala @@ -296,21 +296,23 @@ abstract class DocGenerator extends Models { * @param mmbr ... * @return ... */ - def listSubclasses(mmbr: HasTree): NodeSeq = - if (!subclasses(mmbr.tree.symbol).isEmpty) + def listSubclasses(mmbr: HasTree): NodeSeq = { + val subcs = subclasses(mmbr.tree.symbol) + if (subcs.isEmpty) + NodeSeq.Empty + else <dl> <dt style="margin:10px 0 0 20px;"> <b>Direct known subclasses:</b> </dt> <dd>{ { val links = - for (val subc <- subclasses(mmbr.tree.symbol)) yield + for (val subc <- subcs) yield aref(urlFor(subc), contentFrame, subc.nameString) links.reduceRight { (link: Seq[Node], seq: Seq[Node]) => link.concat(Text(", ")).concat(seq) } } }</dd> </dl>; - else - NodeSeq.Empty + } def lists(mmbr: HasTree) = mmbr match { case cmod: ImplMod => <span>{ listMembersShort(mmbr) } @@ -578,18 +580,19 @@ abstract class DocGenerator extends Models { for (val unit <- units) { val sourceMod = new SourceMod(unit) for (val mmbr <- sourceMod.members) mmbr.tree match { - case cdef: ImplDef => + case cdef: ImplDef => assert(cdef.symbol.owner != NoSymbol) val sym = cdef.symbol.owner.asInstanceOf[ModuleClassSymbol] if (!sym.isEmptyPackageClass) { - if (!topLevel.contains(sym)) topLevel = topLevel.update(sym, emptyMap) + if (!topLevel.contains(sym)) + topLevel = topLevel.update(sym, emptyMap) topLevel = topLevel.update(sym, organize0(mmbr, topLevel(sym))) } for (val p <- cdef.symbol.info.parents) { subclasses(p.symbol) = cdef.symbol :: subclasses(p.symbol) } - import Flags._; - val mmbrs = cdef.symbol.info.findMember(nme.ANYNAME, MUTABLE | METHOD | BRIDGE | ACCESSOR, 0, false).alternatives; + import Flags._ + val mmbrs = cdef.symbol.info.findMember(nme.ANYNAME, MUTABLE | METHOD | BRIDGE | ACCESSOR, 0, false).alternatives for (val c <- mmbrs; c.isClass) for (val p <- c.info.parents) { subclasses(p.symbol) = c :: subclasses(p.symbol) diff --git a/src/library/scala/collection/BitSet.scala b/src/library/scala/collection/BitSet.scala index 3bbb7e4ebf..d6607058cf 100644 --- a/src/library/scala/collection/BitSet.scala +++ b/src/library/scala/collection/BitSet.scala @@ -15,7 +15,7 @@ package scala.collection /** <p> * The class <code>BitSet</code> provides the interface for a space-efficient * implementation of dense integer sets represented as bits in array of - * integers. Bit indices are between 0..(capacity-1) inclusive. + * integers. Bit indices are between <code>0..(capacity-1)</code> inclusive. * </p> * * @author Burak Emir, Stephane Micheloud, Nikolay Mihaylov diff --git a/src/library/scala/collection/MapProxy.scala b/src/library/scala/collection/MapProxy.scala index d780c9ed65..54aeccde36 100644 --- a/src/library/scala/collection/MapProxy.scala +++ b/src/library/scala/collection/MapProxy.scala @@ -12,7 +12,8 @@ package scala.collection -/** This is a simple wrapper class for <code>scala.collection.Map</code>. +/** This is a simple wrapper class for <a href="Map.html" + * target="contentFrame"><code>scala.collection.Map</code></a>. * It is most useful for assembling customized map abstractions * dynamically using object composition and forwarding. * diff --git a/src/library/scala/collection/SetProxy.scala b/src/library/scala/collection/SetProxy.scala index 41d2d13b35..4d770daec9 100644 --- a/src/library/scala/collection/SetProxy.scala +++ b/src/library/scala/collection/SetProxy.scala @@ -12,7 +12,8 @@ package scala.collection -/** This is a simple wrapper class for <code>scala.collection.Set</code>. +/** This is a simple wrapper class for <a href="Set.html" + * target="contentFrame"><code>scala.collection.Set</code></a>. * It is most useful for assembling customized set abstractions * dynamically using object composition and forwarding. * diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala index 2e16c68322..1f3af38ee0 100644 --- a/src/library/scala/collection/immutable/BitSet.scala +++ b/src/library/scala/collection/immutable/BitSet.scala @@ -12,9 +12,9 @@ package scala.collection.immutable -/** The class <code>BitSet</code>provides an immutable bitset view on an +/** The class <code>BitSet</code> provides an immutable bitset view on an * int array. Instances can conveniently be created from instances of - * Bit indices are between 0..(capacity-1) inclusive + * Bit indices are between <code>0..(capacity-1)</code> inclusive. * * @param size <code>size</code> represents the number of relevant bits * @param capacity ... @@ -33,7 +33,7 @@ class BitSet(val size: Int, val capacity: Int, ba: Array[Int], copy: Boolean) { import compat.Platform.arraycopy - protected val arr: Array[Int] = + protected val arr: Array[Int] = if (copy) { val arr = new Array[Int](ba.length) arraycopy(ba, 0, arr, 0, ba.length) diff --git a/src/library/scala/collection/immutable/Map.scala b/src/library/scala/collection/immutable/Map.scala index 3841681a71..787d5d1670 100644 --- a/src/library/scala/collection/immutable/Map.scala +++ b/src/library/scala/collection/immutable/Map.scala @@ -12,13 +12,21 @@ package scala.collection.immutable -/** This class extends the Map interface of collections that unambiguously map - * keys to values (i.e. a key is mapped to at least one value). - * This class defines the interface for functional map implementations - * relying on immutable data structures. - * Concrete map implementations have to provide functionality for the - * abstract methods in scala.collection.Map as well as for - * <code>factory</code>, <code>update</code>, and -. +/** <p> + * This class extends the <code>Map</code> interface of collections + * that unambiguously map keys to values (i.e. a key is mapped to at + * least one value). + * </p> + * <p> + * This class defines the interface for functional map implementations + * relying on immutable data structures. + * </p> + * <p> + * Concrete map implementations have to provide functionality for + * the abstract methods in <a href="../Map.html" target="contentFrame"> + * <code>scala.collection.Map</code></a> as well as for + * <code>factory</code>, <code>update</code>, and <code>-</code>. + * </p> * * @author Matthias Zenger * @author Erik Stenman @@ -36,6 +44,10 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] { * to <code>value</code>. If the map contains already a * mapping for <code>key</code>, it will be overridden by this * function. + * + * @param key ... + * @param value ... + * @return the created map */ def update(key: A, value: B): Map[A, B] @@ -45,10 +57,12 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] { */ def -(key: A): Map[A, B] - /** This method defines syntactic sugar for adding a - * mapping. It is typically used in the following way: + /** <p> + * This method defines syntactic sugar for adding a + * mapping. It is typically used in the following way: + * </p> * <pre> - * map + key -> value; + * map + key -> value * </pre> */ def +(key: A): MapTo = new MapTo(key) @@ -57,6 +71,9 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] { * to the map. The method assumes that a mapping is represented * by a <code>Pair</code> object who's first component denotes the * key, and who's second component refers to the value. + * + * @param mappings ... + * @return ... */ def incl(mappings: Pair[A, B]*): Map[A, B] = incl(mappings) @@ -81,6 +98,7 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] { * for the given sequence of keys are removed from the map. * * @param keys ... + * @return the updated map */ def excl(keys: A*): Map[A, B] = excl(keys) @@ -88,6 +106,7 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] { * iterator over the elements of the <code>keys</code> object. * * @param keys ... + * @return the updated map */ def excl(keys: Iterable[A]): Map[A, B] = { val iter = keys.elements @@ -102,6 +121,7 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] { * in this map with function <code>f</code>. * * @param f A function over key-value pairs + * @return the updated map */ def map[C](f: Pair[A, B] => C): Map[A, C] = { var res = empty[C] @@ -114,6 +134,7 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] { * <code>p</code> returns <code>false</code>. * * @param p A prediacte over key-value pairs + * @return the updated map */ def filter(p: Pair[A, B] => Boolean): Map[A, B] = { var res = this @@ -144,6 +165,9 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] { /** This method controls how a mapping is represented in the string * representation provided by method <code>toString</code>. + * + * @param p ... + * @return the string representation of a map entry */ def mappingToString(p: Pair[A, B]) = p._1.toString() + " -> " + p._2 diff --git a/src/library/scala/collection/immutable/Tree.scala b/src/library/scala/collection/immutable/Tree.scala index 5f2673156a..96311936ba 100644 --- a/src/library/scala/collection/immutable/Tree.scala +++ b/src/library/scala/collection/immutable/Tree.scala @@ -41,19 +41,29 @@ package scala.collection.immutable import java.util.NoSuchElementException -/** General Balanced Trees - highly efficient functional dictionaries. - * - * <p>An efficient implementation of Prof. Arne Andersson's General - * Balanced Trees. These have no storage overhead compared to plain - * unbalanced binary trees, and their performance is in general better - * than AVL trees.</p> - * <p>This implementation does not balance the trees after deletions. - * Since deletions don't increase the height of a tree, this should - * be OK in most applications. A balance method is provided for those - * cases where rebalancing is needed.</p> - * <p>The tree consists of entries conatining a key with an order.</p> - * <p>When instanciating the tree an order for the keys has to be - * supplied.</p> +/** <p> + * General Balanced Trees - highly efficient functional dictionaries. + * </p> + * <p> + * An efficient implementation of Prof. Arne Andersson's + * <a href="http://citeseer.ist.psu.edu/andersson99general.html" + * target="_top">General Balanced Trees</a>. These have no storage overhead + * compared to plain unbalanced binary trees, and their performance is in + * general better than AVL trees. + * </p> + * <p> + * This implementation does not balance the trees after deletions. + * Since deletions don't increase the height of a tree, this should + * be OK in most applications. A balance method is provided for those + * cases where rebalancing is needed. + * </p> + * <p> + * The tree consists of entries conatining a key with an order. + * </p> + * <p> + * When instanciating the tree an order for the keys has to be + * supplied. + * </p> * * @author Erik Stenman, Michel Schinz * @version 1.1, 2005-01-20 @@ -92,18 +102,21 @@ abstract class Tree[A <% Ordered[A], B]() extends AnyRef { */ protected def tree: aNode = GBLeaf[A,B]() - /** This abstract method should be defined by a concrete implementation - * C[T] as something like: - * <pre> - * override def New(sz:Int,t:aNode):This { - * new C[T](order) { - * override def size=sz; - * override protected def tree:aNode=t; - * } - * </pre> - * The concrete implementation should also override the def of This - * <code>override type This = C[T];</code> - * + /** <p> + * This abstract method should be defined by a concrete implementation + * <code>C[T]</code> as something like: + * </p> + * <pre> + * <b>override def</b> New(sz: Int, t: aNode): This { + * <b>new</b> C[T](order) { + * <b>override def</b> size = sz + * <b>override protected def</b> tree: aNode = t + * } + * </pre> + * <p> + * The concrete implementation should also override the def of This + * <code>override type This = C[T];</code> + * </p> */ protected def New(sz: Int, t: aNode): This @@ -157,8 +170,8 @@ abstract class Tree[A <% Ordered[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 */ protected def findValue(key: A): Option[B] = tree.get(key) @@ -360,7 +373,11 @@ private case class GBNode[A <% Ordered[A],B](key: A, Triple(key1, value1, GBNode(key, value, smaller1, bigger)) } - def balance(s:int): GBTree[A,B] = + /** + * @param s ... + * @return ... + */ + def balance(s: int): GBTree[A,B] = balance_list(toList(scala.Nil), s) protected def balance_list(list: List[Pair[A,B]], s: int): GBTree[A,B] = { @@ -374,12 +391,11 @@ private case class GBNode[A <% Ordered[A],B](key: A, val Pair(t2, l2) = bal(l1, s2) val t = GBNode(k, v, t1, t2) Pair(t, l2) + } else if (s == 1) { + val Pair(k,v) :: rest = list + Pair(GBNode(k, v, empty, empty), rest) } else - if (s == 1) { - val Pair(k,v) :: rest = list - Pair(GBNode(k, v, empty, empty), rest) - } else - Pair(empty, list) + Pair(empty, list) } bal(list, s)._1 } diff --git a/src/library/scala/collection/mutable/ArrayBuffer.scala b/src/library/scala/collection/mutable/ArrayBuffer.scala index 97bfe642a4..8dacd17489 100644 --- a/src/library/scala/collection/mutable/ArrayBuffer.scala +++ b/src/library/scala/collection/mutable/ArrayBuffer.scala @@ -14,7 +14,7 @@ package scala.collection.mutable import Predef._ -/** An implementation of the Buffer class using an array to +/** An implementation of the <code>Buffer</code> class using an array to * represent the assembled sequence internally. * * @author Matthias Zenger @@ -23,7 +23,7 @@ import Predef._ [serializable] class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] { - /** Append a single element to this buffer and return + /** Appends a single element to this buffer and returns * the identity of the buffer. * * @param elem the element to append. @@ -39,13 +39,17 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] { * buffer is returned. * * @param iter the iterable object. + * @return the updated buffer. */ - override def ++(iter: Iterable[A]): Buffer[A] = { insertAll(size, iter); this } + override def ++(iter: Iterable[A]): Buffer[A] = { + insertAll(size, iter); this + } - /** Prepend a single element to this buffer and return + /** Prepends a single element to this buffer and return * the identity of the buffer. * * @param elem the element to append. + * @return the updated buffer. */ def +:(elem: A): Buffer[A] = { ensureSize(size+1) @@ -55,8 +59,11 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] { this } - /** returns the i-th element of this ArrayBuffer. Throws IndexOutOfBoundException if - * i is out of bounds. + /** Returns the i-th element of this ArrayBuffer. + * + * @param i the specified index. + * @return the i-th element. + * @throws IndexOutOfBoundException if <code>i</code> is out of bounds. */ override def apply(i: Int) = { if ((i < 0) || (i >= size)) @@ -70,6 +77,7 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] { * buffer is returned. * * @param iter the iterable object. + * @return the updated buffer. */ override def ++:(iter: Iterable[A]): Buffer[A] = { insertAll(0, iter); this } @@ -79,16 +87,17 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] { * * @param n the index where a new element will be inserted. * @param iter the iterable object providing all elements to insert. + * @throws IndexOutOfBoundsException if <code>n</code> is out of bounds. */ def insertAll(n: Int, iter: Iterable[A]): Unit = { if ((n < 0) || (n > size)) throw new IndexOutOfBoundsException("cannot insert element at " + n); - val xs = iter.elements.toList; - val len = xs.length; - ensureSize(size+len); - copy(n, n + len, size - n); - xs.copyToArray(array, n); - size = size + len; + val xs = iter.elements.toList + val len = xs.length + ensureSize(size+len) + copy(n, n + len, size - n) + xs.copyToArray(array, n) + size = size + len } /** Replace element at index <code>n</code> with the new element @@ -96,6 +105,7 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] { * * @param n the index of the element to replace. * @param newelem the new element. + * @throws IndexOutOfBoundsException if <code>n</code> is out of bounds. */ def update(n: Int, newelem: A): Unit = { if ((n < 0) || (n >= size)) @@ -110,6 +120,8 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] { /** Removes the element on a given index position. * * @param n the index which refers to the element to delete. + * @return the updated array buffer. + * @throws IndexOutOfBoundsException if <code>n</code> is out of bounds. */ def remove(n: Int): A = { if ((n < 0) || (n >= size)) @@ -123,7 +135,7 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] { /** Clears the buffer contents. */ def clear: Unit = { - size = 0; + size = 0 } /** Return a clone of this buffer. @@ -131,8 +143,8 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] { * @return an <code>ArrayBuffer</code> with the same elements. */ override def clone(): Buffer[A] = { - val res = new ArrayBuffer[A]; - res ++= this; + val res = new ArrayBuffer[A] + res ++= this res } diff --git a/src/library/scala/collection/mutable/BufferProxy.scala b/src/library/scala/collection/mutable/BufferProxy.scala index 86b80613fd..c43b34ef2b 100644 --- a/src/library/scala/collection/mutable/BufferProxy.scala +++ b/src/library/scala/collection/mutable/BufferProxy.scala @@ -12,7 +12,8 @@ package scala.collection.mutable -/** This is a simple proxy class for <code>scala.collection.mutable.Buffer</code>. +/** This is a simple proxy class for <a href="Buffer.html" + * target="contentFrame"><code>scala.collection.mutable.Buffer</code></a>. * It is most useful for assembling customized set abstractions * dynamically using object composition and forwarding. * diff --git a/src/library/scala/collection/mutable/History.scala b/src/library/scala/collection/mutable/History.scala index 85b081e0ea..676d798961 100644 --- a/src/library/scala/collection/mutable/History.scala +++ b/src/library/scala/collection/mutable/History.scala @@ -27,6 +27,10 @@ class History[A, B] extends AnyRef with Subscriber[A, B] with Iterable[Pair[B, A val maxHistory: Int = 1000 + /** + * @param pub ... + * @param event ... + */ def notify(pub: B, event: A): Unit = { if (log.length >= maxHistory) { val old = log.dequeue; diff --git a/src/library/scala/collection/mutable/MapProxy.scala b/src/library/scala/collection/mutable/MapProxy.scala index 872ae4a48d..20c326b968 100644 --- a/src/library/scala/collection/mutable/MapProxy.scala +++ b/src/library/scala/collection/mutable/MapProxy.scala @@ -12,9 +12,14 @@ package scala.collection.mutable -/** This is a simple wrapper class for <code>scala.collection.mutable.Map</code>. - * It is most useful for assembling customized map abstractions - * dynamically using object composition and forwarding. +/** <p> + * This is a simple wrapper class for <a href="Map.html" + * target="contentFrame"><code>scala.collection.mutable.Map</code></a>. + * </p> + * <p> + * It is most useful for assembling customized map abstractions + * dynamically using object composition and forwarding. + * </p> * * @author Matthias Zenger * @version 1.0, 21/07/2003 diff --git a/src/library/scala/collection/mutable/Set.scala b/src/library/scala/collection/mutable/Set.scala index b64cd35db0..ec8dfd2fd2 100644 --- a/src/library/scala/collection/mutable/Set.scala +++ b/src/library/scala/collection/mutable/Set.scala @@ -13,7 +13,8 @@ package scala.collection.mutable /** This class represents mutable sets. Concrete set implementations * just have to provide functionality for the abstract methods in - * <code>scala.collection.Set</code> as well as for <code>add</code>, + * <a href="../Set.html" target="contentFrame"> + * <code>scala.collection.Set</code></a> as well as for <code>add</code>, * <code>remove</code>, and <code>clear</code>. * * @author Matthias Zenger @@ -46,7 +47,7 @@ trait Set[A] extends AnyRef with collection.Set[A] * * @param that ... */ - def ++=(that: Iterable[A]): Unit = ++=(that.elements); + def ++=(that: Iterable[A]): Unit = ++=(that.elements) /** This method will add all the elements provided by an iterator * of the iterable object <code>that</code> to the set. @@ -103,6 +104,7 @@ trait Set[A] extends AnyRef with collection.Set[A] /** Send a message to this scriptable object. * * @param cmd the message to send. + * @throws UnsupportedOperationException if the message was not understood. */ def <<(cmd: Message[A]): Unit = cmd match { case Include(elem) => this += elem @@ -118,10 +120,11 @@ trait Set[A] extends AnyRef with collection.Set[A] */ override def clone(): Set[A] = super.clone().asInstanceOf[Set[A]] - /** The hashCode method always yields an error, since it is not - * safe to use mutable stacks as keys in hash tables. + /** The <code>hashCode</code> method always yields an error, since it is + * not safe to use mutable stacks as keys in hash tables. * * @return never. */ - override def hashCode(): Int = throw new UnsupportedOperationException("unsuitable as hash key") + override def hashCode(): Int = + throw new UnsupportedOperationException("unsuitable as hash key") } diff --git a/src/library/scala/collection/mutable/SetProxy.scala b/src/library/scala/collection/mutable/SetProxy.scala index 8356b4b0ba..54c0c753b5 100644 --- a/src/library/scala/collection/mutable/SetProxy.scala +++ b/src/library/scala/collection/mutable/SetProxy.scala @@ -12,7 +12,8 @@ package scala.collection.mutable -/** This is a simple wrapper class for <code>scala.collection.mutable.Set</code>. +/** This is a simple wrapper class for <a href="Set.html" + * target="contentFrame"><code>scala.collection.mutable.Set</code></a>. * It is most useful for assembling customized set abstractions * dynamically using object composition and forwarding. * diff --git a/src/library/scala/collection/mutable/Subscriber.scala b/src/library/scala/collection/mutable/Subscriber.scala index 330a5a2c22..b6c33a8b1b 100644 --- a/src/library/scala/collection/mutable/Subscriber.scala +++ b/src/library/scala/collection/mutable/Subscriber.scala @@ -14,11 +14,12 @@ package scala.collection.mutable /** <code>Subscriber[A, B]</code> objects may subscribe to events of * type <code>A</code> published by an object of type <code>B</code>. - * <code>B</code> is typically a subtype of <code>Publisher</code>. + * <code>B</code> is typically a subtype of <a href="Publisher.html" + * target="contentFrame"><code>Publisher</code></a>. * * @author Matthias Zenger * @version 1.0, 08/07/2003 */ trait Subscriber[-A, -B] { - def notify(pub: B, event: A): Unit + def notify(pub: B, event: A): Unit } diff --git a/src/library/scala/io/Source.scala b/src/library/scala/io/Source.scala index 4087ded64e..a384af99df 100644 --- a/src/library/scala/io/Source.scala +++ b/src/library/scala/io/Source.scala @@ -23,10 +23,11 @@ import compat.StringBuilder */ object Source { - /** Creates Source from array of bytes, with empty description. + /** Creates a <code>Source</code> instance from the given array of bytes, + * with empty description. * * @param bytes ... - * @return ... + * @return the created <code>Source</code> instance. */ def fromBytes(bytes: Array[Byte]): Source = fromString(new String(bytes)) @@ -41,10 +42,10 @@ object Source { def fromBytes(bytes: Array[Byte], enc: String): Source = fromString(new String(bytes, enc)) - /** Creates Source from a single character. + /** Creates a <code>Source</code> instance from a single character. * * @param c ... - * @return ... + * @return the create <code>Source</code> instance. */ def fromChar(c: Char): Source = { val it = Iterator.single(c) @@ -134,9 +135,17 @@ object Source { s } - def fromURL(s:String): Source = + /** + * @param s ... + * @return ... + */ + def fromURL(s: String): Source = fromURL(new java.net.URL(s)) + /** + * @param url ... + * @return ... + */ def fromURL(url: java.net.URL): Source = { val it = new Iterator[Char] { var data: Int = _ @@ -156,8 +165,9 @@ object Source { } -/** an iterable representation of source files. - * calling method reset returns an identical, resetted source +/** The class <code>Source</code> implements an iterable representation + * of source files. Calling method <code>reset</code> returns an identical, + * resetted source. * * @author Burak Emir * @version 1.0 @@ -197,18 +207,22 @@ abstract class Source extends Iterator[Char] { // /** convenience method, returns given line (not including newline) - * from Source + * from Source. + * + * @param line the line index. + * @return the character string of the specified line. + * @throws IllegalArgumentException */ def getLine(line: Int): String = { val buf = new StringBuffer() val it = reset var i = 0 - while( it.hasNext && i < (line-1)) - if('\n' == it.next) + while (it.hasNext && i < (line-1)) + if ('\n' == it.next) i = i + 1; - if(!it.hasNext) // this should not happen + if (!it.hasNext) // this should not happen throw new java.lang.IllegalArgumentException( "line "+line+" does not exist?!" ); @@ -222,7 +236,7 @@ abstract class Source extends Iterator[Char] { buf.setLength(0) res } - /** returns true if this source has more characters + /** Returns <code>true</code> if this source has more characters. */ def hasNext = iter.hasNext @@ -271,7 +285,7 @@ abstract class Source extends Iterator[Char] { val buf = new StringBuffer val line = Position.line(pos) val col = Position.column(pos) - buf.append(descr + ":"+line+":"+col+": "+msg) + buf.append(descr + ":" + line + ":" + col + ": " + msg) buf.append(getLine(line)) var i = 1 while (i < col) { diff --git a/src/library/scala/runtime/RichString.scala b/src/library/scala/runtime/RichString.scala index d6195e034b..97836fc54b 100755 --- a/src/library/scala/runtime/RichString.scala +++ b/src/library/scala/runtime/RichString.scala @@ -21,16 +21,25 @@ final class RichString(s: String) { private def isLineBreak(c: Char) = c == LF || c == FF - /** Treat string as a function that maps indices to characters + /** Treat string as a function that maps indices to characters. + * + * @param index ... + * @return the character at position <code>index</code>. */ def apply(index: Int): Char = s charAt index - /** Strip trailing line end character from this string if it has one. - * A line end character is one of - * LF - line feed (0x0A hex) - * FF - form feed (0x0C hex) - * If a line feed character LF is preceded by a carriage return CR (0x0D hex), - * the CR character is also stripped (Windows convention) + /** <p> + * Strip trailing line end character from this string if it has one. + * A line end character is one of + * </p> + * <ul style="list-style-type: none;"> + * <li>LF - line feed (0x0A hex)</li> + * <li>FF - form feed (0x0C hex)</li> + * </ul> + * <p> + * If a line feed character LF is preceded by a carriage return CR + * (0x0D hex), the CR character is also stripped (Windows convention). + * </p> */ def stripLineEnd: String = { val len = s.length @@ -44,12 +53,19 @@ final class RichString(s: String) { } } - /** Return all lines in this string in an iterator, including trailing line end characters - * The number of strings returned is one greater than the number of line end characters - * in this string. For an empty string, a single empty line is returned. - * A line end character is one of - * LF - line feed (0x0A hex) - * FF - form feed (0x0C hex) + /** <p> + * Return all lines in this string in an iterator, including trailing + * line end characters. + * </p> + * <p> + * The number of strings returned is one greater than the number of line + * end characters in this string. For an empty string, a single empty + * line is returned. A line end character is one of + * </p> + * <ul style="list-style-type: none;"> + * <li>LF - line feed (0x0A hex)</li> + * <li>FF - form feed (0x0C hex)</li> + * </ul> */ def linesWithSeparators = new Iterator[String] { val len = s.length @@ -64,14 +80,19 @@ final class RichString(s: String) { } } - /** Return all lines in this string in an iterator, excluding trailing line end characters - * I.e. apply `.stripLineEnd' to all lines returned by `linesWithSeparators' + /** Return all lines in this string in an iterator, excluding trailing line + * end characters, i.e. apply <code>.stripLineEnd</code> to all lines + * returned by <code>linesWithSeparators</code>. */ def lines = linesWithSeparators map (line => new RichString(line).stripLineEnd) - /** For every line in this string: - * Strip a leading prefix consisting of blanks or control characters followed by - * `marginChar' from the line. + /** <p> + * For every line in this string: + * </p> + * <blockquote> + * Strip a leading prefix consisting of blanks or control characters + * followed by <code>marginChar</code> from the line. + * </blockquote> */ def stripMargin(marginChar: Char): String = { val buf = new scala.compat.StringBuilder() @@ -85,9 +106,13 @@ final class RichString(s: String) { buf.toString } - /** For every line in this string: - * Strip a leading prefix consisting of blanks or control characters followed by - * `|' from the line. + /** <p> + * For every line in this string: + * </p> + * <blockquote> + * Strip a leading prefix consisting of blanks or control characters + * followed by <code>|</code> from the line. + * </blockquote> */ def stripMargin: String = stripMargin('|') } diff --git a/src/library/scala/util/logging/Logged.scala b/src/library/scala/util/logging/Logged.scala index 6d9e423a02..5c8aa2808a 100644 --- a/src/library/scala/util/logging/Logged.scala +++ b/src/library/scala/util/logging/Logged.scala @@ -11,22 +11,27 @@ package scala.util.logging -/** - * Mixing in the class Logged indicates that a class provides support - * for logging. For instance, a developer of a library writes - * <code> - class MyClass with Logged { ... do stuff, call log } - </code> - * - * The user of the library instantiates: - <code> - val x = new MyClass() with ConsoleLogger; - </code> - * and the logging will be sent to the Console. - */ +/** <p> + * Mixing in the class <code>Logged</code> indicates that a class provides + * support for logging. For instance, the developer of a library writes + * </p> + * <pre> + * <b>class</b> MyClass <b>with</b> Logged { /* do stuff, call log */ } + * </pre> + * <p> + * The user of the library instantiates: + * </p> + * <pre> + * <b>val</b> x = <b>new</b> MyClass() <b>with</b> ConsoleLogger + * </pre> + * <p> + * and the logging will be sent to the <a href="../../Console$object.html" + * target="contentFrame"><code>Console</code></a> object. + * </p> + */ trait Logged { - /** this method should log the message given as argument somewhere + /** This method should log the message given as argument somewhere * as a side-effect. * * @param msg ... diff --git a/src/library/scala/xml/NodeSeq.scala b/src/library/scala/xml/NodeSeq.scala index 946951fa75..ff8c1e7ff3 100644 --- a/src/library/scala/xml/NodeSeq.scala +++ b/src/library/scala/xml/NodeSeq.scala @@ -25,8 +25,8 @@ object NodeSeq { implicit def view(s: Seq[Node]): NodeSeq = fromSeq(s) } -/** This class implements a wrapper around Seq[Node] that adds XPath and - * comprehension methods. +/** This class implements a wrapper around <code>Seq[Node]</code> that + * adds XPath and comprehension methods. * * @author Burak Emir * @version 1.0 @@ -43,14 +43,15 @@ abstract class NodeSeq extends Seq[Node] { /** structural equality */ override def equals(x: Any) = x match { case z:Node => (length == 1) && z == apply(0) - case z:Seq[Node] => sameElements( z ) + case z:Seq[Node] => sameElements(z) case z:String => text == z case _ => false; } - /** projection function. Similar to XPath, use this \ "foo" to get a list - * of all elements of this sequence that are labelled with "foo". - * Use \ "_" as a wildcard. The document order is preserved. + /** Projection function. Similar to XPath, use <code>this \ "foo"</code> + * to get a list of all elements of this sequence that are labelled with + * <code>"foo"</code>. Use <code>\ "_"</code> as a wildcard. + * The document order is preserved. * * @param that ... * @return ... @@ -93,9 +94,10 @@ abstract class NodeSeq extends Seq[Node] { NodeSeq.fromSeq(zs.reverse) } - /** projection function. Similar to XPath, use this \\ 'foo to get a list - * of all elements of this sequence that are labelled with "foo". - * Use \\ "_" as a wildcard. The document order is preserved. + /** projection function. Similar to XPath, use <code>this \\ 'foo</code> + * to get a list of all elements of this sequence that are labelled with + * <code>"foo"</code>. Use <code>\\ "_"</code> as a wildcard. + * The document order is preserved. * * @param that ... * @return ... |