From 27de82558058e859d6ec884727d85bc08d972f16 Mon Sep 17 00:00:00 2001 From: michelou Date: Wed, 11 Oct 2006 22:02:11 +0000 Subject: improved comments in scala/collection/*.scala --- .../scala/tools/nsc/doc/DocGenerator.scala | 21 +++--- src/library/scala/collection/BitSet.scala | 2 +- src/library/scala/collection/MapProxy.scala | 3 +- src/library/scala/collection/SetProxy.scala | 3 +- .../scala/collection/immutable/BitSet.scala | 6 +- src/library/scala/collection/immutable/Map.scala | 44 +++++++++--- src/library/scala/collection/immutable/Tree.scala | 82 +++++++++++++--------- .../scala/collection/mutable/ArrayBuffer.scala | 42 +++++++---- .../scala/collection/mutable/BufferProxy.scala | 3 +- src/library/scala/collection/mutable/History.scala | 4 ++ .../scala/collection/mutable/MapProxy.scala | 11 ++- src/library/scala/collection/mutable/Set.scala | 13 ++-- .../scala/collection/mutable/SetProxy.scala | 3 +- .../scala/collection/mutable/Subscriber.scala | 5 +- src/library/scala/io/Source.scala | 40 +++++++---- src/library/scala/runtime/RichString.scala | 67 ++++++++++++------ src/library/scala/util/logging/Logged.scala | 33 +++++---- src/library/scala/xml/NodeSeq.scala | 20 +++--- 18 files changed, 260 insertions(+), 142 deletions(-) (limited to 'src') 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
Direct known subclasses:
{ { 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) } } }
; - else - NodeSeq.Empty + } def lists(mmbr: HasTree) = mmbr match { case cmod: ImplMod => { 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 /**

* The class BitSet 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 0..(capacity-1) inclusive. *

* * @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 scala.collection.Map. +/** This is a simple wrapper class for scala.collection.Map. * 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 scala.collection.Set. +/** This is a simple wrapper class for scala.collection.Set. * 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 BitSetprovides an immutable bitset view on an +/** The class BitSet 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 0..(capacity-1) inclusive. * * @param size size 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 - * factory, update, and -. +/**

+ * 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 + * factory, update, and -. + *

* * @author Matthias Zenger * @author Erik Stenman @@ -36,6 +44,10 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] { * to value. If the map contains already a * mapping for key, 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: + /**

+ * This method defines syntactic sugar for adding a + * mapping. It is typically used in the following way: + *

* 
-   *  map + key -> value;
+   *    map + key -> value
    *
*/ 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 Pair 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 keys 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 f. * * @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] { * p returns false. * * @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 toString. + * + * @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. - * - *

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.

- *

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.

- *

The tree consists of entries conatining a key with an order.

- *

When instanciating the tree an order for the keys has to be - * supplied.

+/**

+ * General Balanced Trees - highly efficient functional dictionaries. + *

+ *

+ * 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. + *

+ *

+ * 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. + *

+ *

+ * The tree consists of entries conatining a key with an order. + *

+ *

+ * When instanciating the tree an order for the keys has to be + * supplied. + *

* * @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: - * 
-   *     override def New(sz:Int,t:aNode):This {
-   *       new C[T](order) {
-   *        override def size=sz;
-   *        override protected def tree:aNode=t;
-   *     }
-   *
- * The concrete implementation should also override the def of This - * override type This = C[T]; - * + /**

+ * This abstract method should be defined by a concrete implementation + * C[T] as something like: + *

+ * 
+   *    override def New(sz: Int, t: aNode): This {
+   *      new C[T](order) {
+   *        override def size = sz
+   *        override protected def tree: aNode = t
+   *    }
+   *
+ *

+ * The concrete implementation should also override the def of This + * override type This = C[T]; + *

*/ 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 key 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 Buffer 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 i 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 n 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 n 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 n 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 n 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 ArrayBuffer 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 scala.collection.mutable.Buffer. +/** This is a simple proxy class for scala.collection.mutable.Buffer. * 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 scala.collection.mutable.Map. - * It is most useful for assembling customized map abstractions - * dynamically using object composition and forwarding. +/**

+ * This is a simple wrapper class for scala.collection.mutable.Map. + *

+ *

+ * It is most useful for assembling customized map abstractions + * dynamically using object composition and forwarding. + *

* * @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 - * scala.collection.Set as well as for add, + * + * scala.collection.Set as well as for add, * remove, and clear. * * @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 that 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 hashCode 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 scala.collection.mutable.Set. +/** This is a simple wrapper class for scala.collection.mutable.Set. * 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 /** Subscriber[A, B] objects may subscribe to events of * type A published by an object of type B. - * B is typically a subtype of Publisher. + * B is typically a subtype of Publisher. * * @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 Source instance from the given array of bytes, + * with empty description. * * @param bytes ... - * @return ... + * @return the created Source 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 Source instance from a single character. * * @param c ... - * @return ... + * @return the create Source 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 Source implements an iterable representation + * of source files. Calling method reset 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 true 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 index. */ 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) + /**

+ * Strip trailing line end character from this string if it has one. + * A line end character is one of + *

+ * + *

+ * If a line feed character LF is preceded by a carriage return CR + * (0x0D hex), the CR character is also stripped (Windows convention). + *

*/ 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) + /**

+ * 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 + *

+ * */ 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 .stripLineEnd to all lines + * returned by linesWithSeparators. */ 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. + /**

+ * For every line in this string: + *

+ *
+ * Strip a leading prefix consisting of blanks or control characters + * followed by marginChar from the line. + *
*/ 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. + /**

+ * For every line in this string: + *

+ *
+ * Strip a leading prefix consisting of blanks or control characters + * followed by | from the line. + *
*/ 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 - * - class MyClass with Logged { ... do stuff, call log } - - * - * The user of the library instantiates: - - val x = new MyClass() with ConsoleLogger; - - * and the logging will be sent to the Console. - */ +/**

+ * Mixing in the class Logged indicates that a class provides + * support for logging. For instance, the developer of a library writes + *

+ * 
+ *    class MyClass with Logged { /* do stuff, call log */ }
+ *
+ *

+ * The user of the library instantiates: + *

+ * 
+ *    val x = new MyClass() with ConsoleLogger
+ *
+ *

+ * and the logging will be sent to the Console object. + *

+ */ 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 Seq[Node] 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 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. * * @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 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. * * @param that ... * @return ... -- cgit v1.2.3