small cleanups in xml/*.scala

7 files changed, 120 insertions, 91 deletions

diff --git a/src/library/scala/xml/Atom.scala b/src/library/scala/xml/Atom.scala
index 0bbf65f979..7f45458101 100644
--- a/src/library/scala/xml/Atom.scala
+++ b/src/library/scala/xml/Atom.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2003-2006, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2007, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
@@ -9,41 +9,47 @@
 // $Id$
 
 
-package scala.xml;
+package scala.xml
 
-import compat.StringBuilder;
+import compat.StringBuilder
 
-/** an XML node for text (PCDATA). Used in both non-bound and bound XML
- *  representations
- * @author Burak Emir
- * @param text the text contained in this node, may not be null.
+/** The class <code>Atom</code> provides an XML node for text (PCDATA).
+ *  It is used in both non-bound and bound XML representations.
+ *
+ *  @author Burak Emir
+ *  @param text the text contained in this node, may not be <code>null</code>.
  */
 [serializable]
-class Atom[+A]( val data: A ) extends SpecialNode {
+class Atom[+A](val data: A) extends SpecialNode {
 
   data match {
     case null => new IllegalArgumentException("cannot construct Atom(null)")
     case _ =>
   }
-  final override def typeTag$:Int = -1;
+  final override def typeTag$: Int = -1
 
   /** the constant "#PCDATA"
-  */
-  def label = "#PCDATA";
+   */
+  def label = "#PCDATA"
 
- override def equals(x:Any) = x match {
+  override def equals(x: Any) = x match {
     case s:Atom[_] => data == s.data
-    case _         => false;
+    case _         => false
   }
 
   /** hashcode for this Text */
   override def hashCode() =
-    data.hashCode();
-
-  /** returns text, with some characters escaped according to XML spec */
+    data.hashCode()
+
+  /** Returns text, with some characters escaped according to the XML
+   *  specification.
+   *
+   *  @param  sb ...
+   *  @return ...
+   */
   def toString(sb: StringBuilder) =
-    Utility.escape( data.toString(), sb );
+    Utility.escape(data.toString(), sb)
 
-  override def text: String = data.toString();
+  override def text: String = data.toString()
 
 }
diff --git a/src/library/scala/xml/Comment.scala b/src/library/scala/xml/Comment.scala
index 484d72def8..95926f1c39 100644
--- a/src/library/scala/xml/Comment.scala
+++ b/src/library/scala/xml/Comment.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2003-2006, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2007, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
@@ -14,15 +14,14 @@ package scala.xml
 
 import compat.StringBuilder
 
-/** an XML node for comments.
+/** The class <code>Comment</code> implements an XML node for comments.
  *
  * @author Burak Emir
- * @param text text contained in this node, may not contain "--"
+ * @param text the text contained in this node, may not contain "--"
  */
-
 case class Comment(commentText: String) extends SpecialNode {
 
-  final override def typeTag$:Int = -3
+  final override def typeTag$: Int = -3
 
   if (commentText.indexOf("--") != -1)
     throw new IllegalArgumentException("text containts \"--\"")
@@ -41,7 +40,8 @@ case class Comment(commentText: String) extends SpecialNode {
 
   override def text = ""
 
-  /** appends &quot;<!-- text -->&quot; to this stringbuffer */
+  /** Appends &quot;<!-- text -->&quot; to this string buffer.
+   */
   override def toString(sb: StringBuilder) =
     sb.append("<!--").append(commentText).append("-->")
 }
diff --git a/src/library/scala/xml/Elem.scala b/src/library/scala/xml/Elem.scala
index 77941f1c60..c5794dbcd0 100644
--- a/src/library/scala/xml/Elem.scala
+++ b/src/library/scala/xml/Elem.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2002-2006, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2002-2007, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
@@ -9,17 +9,18 @@
 // $Id$
 
 
-package scala.xml;
+package scala.xml
 
 
-/** The case class <code>Elem</code> extends the Node class,
+/** The case class <code>Elem</code> extends the <code>Node</code> class,
  *  providing an immutable data object representing an XML element.
  *
+ *  @author Burak Emir
+ *
  *  @param prefix (may be null)
  *  @param label the element name
  *  @param attribute the attribute map
  *  @param child the children of this node
- *  @author  Burak Emir
  */
 // "val" is redundant for non-overriding arguments
 case class Elem(override val prefix: String,
@@ -29,23 +30,23 @@ case class Elem(override val prefix: String,
                 val child: Node*) extends Node {
 
   if ((null != prefix) && 0 == prefix.length())
-    throw new IllegalArgumentException("prefix of zero length, use null instead");
+    throw new IllegalArgumentException("prefix of zero length, use null instead")
 
   if (null == scope)
-    throw new IllegalArgumentException("scope is null, try xml.TopScope for empty scope");
+    throw new IllegalArgumentException("scope is null, try xml.TopScope for empty scope")
 
   //@todo: copy the children,
   //  setting namespace scope if necessary
   //  cleaning adjacent text nodes if necessary
 
-  final override def typeTag$: Int = 0;
+  final override def typeTag$: Int = 0
+
+  override def hashCode(): Int =
+    Utility.hashCode(prefix, label, attributes.hashCode(), scope.hashCode(), child)
 
-  override def hashCode(): Int = {
-    Utility.hashCode(prefix, label, attributes.hashCode(), scope.hashCode(), child);
-  }
-  /** Return a new element with updated attributes
+  /** Returns a new element with updated attributes.
    *
-   *  @param attrs
+   *  @param  attrs ...
    *  @return a new symbol with updated attributes
    */
   final def %(attrs: MetaData): Elem =
@@ -53,15 +54,16 @@ case class Elem(override val prefix: String,
          label,
          attrs.append(attributes),
          scope,
-         child:_*);
+         child:_*)
 
-   /* returns concatenation of text(n) for each child n */
+   /** Returns concatenation of <code>text(n)</code> for each child
+    *  <code>n</code>.
+    */
    override def text = {
-     val sb = new compat.StringBuilder();
-     val it = child.elements;
-     while(it.hasNext) {
-       sb.append(it.next.text);
-     }
+     val sb = new compat.StringBuilder()
+     val it = child.elements
+     while (it.hasNext)
+       sb.append(it.next.text)
      sb.toString()
    }
 
diff --git a/src/library/scala/xml/EntityRef.scala b/src/library/scala/xml/EntityRef.scala
index 33cdef33e3..8426e15031 100644
--- a/src/library/scala/xml/EntityRef.scala
+++ b/src/library/scala/xml/EntityRef.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2003-2006, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2007, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
@@ -13,11 +13,12 @@ package scala.xml
 
 import compat.StringBuilder
 
-/** an XML node for entity references
+/** The class <code>EntityRef</code> implements an XML node for entity
+ *  references.
  *
  * @author  Burak Emir
  * @version 1.0
- * @param   text the text contained in this node
+ * @param   text the text contained in this node.
  */
 case class EntityRef(entityName: String) extends SpecialNode {
 
@@ -30,21 +31,27 @@ case class EntityRef(entityName: String) extends SpecialNode {
   }
 
   /** the constant "#ENTITY"
-  */
+   */
   def label = "#ENTITY"
 
   override def hashCode() = entityName.hashCode()
 
+  /** ...
+   */
   override def text = entityName match {
-   case "lt"   => "<"
-   case "gt"   => ">"
-   case "amp"  => "&"
-   case "apos" => "'"
-   case "quot" => "\""
-   case _ => val sb = new StringBuilder(); toString(sb).toString()
+    case "lt"   => "<"
+    case "gt"   => ">"
+    case "amp"  => "&"
+    case "apos" => "'"
+    case "quot" => "\""
+    case _ => val sb = new StringBuilder(); toString(sb).toString()
   }
 
-  /** appends "&amp; entityName;" to this stringbuffer */
+  /** Appends "&amp; entityName;" to this string buffer.
+   *
+   *  @param  sb the string buffer.
+   *  @return the modified string buffer <code>sb</code>.
+   */
   override def toString(sb: StringBuilder) =
     sb.append("&").append(entityName).append(";")
 
diff --git a/src/library/scala/xml/Group.scala b/src/library/scala/xml/Group.scala
index 745b771794..e7c8313db5 100644
--- a/src/library/scala/xml/Group.scala
+++ b/src/library/scala/xml/Group.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2003-2006, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2007, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
@@ -30,7 +30,7 @@ case class Group(val nodes: Seq[Node]) extends Node {
     case z:Node      => (length == 1) && z == apply(0)
     case z:Seq[_]    => sameElements(z)
     case z:String    => text == z
-    case _           => false;
+    case _           => false
   }
 
   /**
@@ -61,7 +61,8 @@ case class Group(val nodes: Seq[Node]) extends Node {
    * @throws Predef.UnsupportedOperationException (always)
    */
   def toString(sb: StringBuilder) =
-    throw new UnsupportedOperationException("class Group does not support method toString(StringBuilder)")
+    throw new UnsupportedOperationException(
+      "class Group does not support method toString(StringBuilder)")
 
   override def text = { // same impl as NodeSeq
     val sb = new StringBuilder()
diff --git a/src/library/scala/xml/Text.scala b/src/library/scala/xml/Text.scala
index 32b93e731f..7170239611 100644
--- a/src/library/scala/xml/Text.scala
+++ b/src/library/scala/xml/Text.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2003-2006, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2007, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
@@ -13,10 +13,12 @@ package scala.xml
 
 import compat.StringBuilder
 
-/** an XML node for text (PCDATA). Used in both non-bound and bound XML
- *  representations
- * @author Burak Emir
- * @param text the text contained in this node, may not be null.
+/** The class <code>Text</code> implements an XML node for text (PCDATA).
+ *  It is used in both non-bound and bound XML representations.
+ *
+ *  @author Burak Emir
+ *
+ *  @param text the text contained in this node, may not be null.
  */
 case class Text(_data: String) extends Atom[String](_data) {
 
@@ -29,7 +31,12 @@ case class Text(_data: String) extends Atom[String](_data) {
     case _ => false
   }
 
-  /** returns text, with some characters escaped according to XML spec */
+  /** Returns text, with some characters escaped according to the XML
+   *  specification.
+   *
+   *  @param  sb ...
+   *  @return ...
+   */
   override def toString(sb: StringBuilder) =
     Utility.escape(data.toString(), sb)
 
diff --git a/src/library/scala/xml/TextBuffer.scala b/src/library/scala/xml/TextBuffer.scala
index d0398165f3..7831b38621 100644
--- a/src/library/scala/xml/TextBuffer.scala
+++ b/src/library/scala/xml/TextBuffer.scala
@@ -1,6 +1,6 @@
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
-**    / __/ __// _ | / /  / _ |    (c) 2003-2006, LAMP/EPFL             **
+**    / __/ __// _ | / /  / _ |    (c) 2003-2007, LAMP/EPFL             **
 **  __\ \/ /__/ __ |/ /__/ __ |                                         **
 ** /____/\___/_/ |_/____/_/ | |                                         **
 **                          |/                                          **
@@ -9,51 +9,57 @@
 // $Id$
 
 
-package scala.xml;
+package scala.xml
 
 
 object TextBuffer {
-  def fromString(str: String): TextBuffer = {
-    new TextBuffer().append( str );
-  }
+  def fromString(str: String): TextBuffer =
+    new TextBuffer().append(str)
 }
 
-/** this classes is for creating text nodes without surplus whitespace.
- *  all occurrences of one or more whitespace in strings appended with the
- *  append method will be replaced by a single space character, and
- *  leading and trailing space will be removed completely.
+/** The class <code>TextBuffer</code> is for creating text nodes without
+ *  surplus whitespace. All occurrences of one or more whitespace in strings
+ *  appended with the <code>append</code> method will be replaced by a single
+ *  space character, and leading and trailing space will be removed completely.
  */
 class TextBuffer {
 
-  val sb = new compat.StringBuilder();
-  var ws = true;
+  val sb = new compat.StringBuilder()
+  var ws = true
 
-  def appendSpace        = if( !ws ) { ws = true;  sb.append(' ');} else {};
-  def appendChar(c:char) =           { ws = false; sb.append( c );}
+  def appendSpace         = if(!ws) { ws = true;  sb.append(' ') } else {}
+  def appendChar(c: char) =         { ws = false; sb.append( c ) }
 
-  /** appends this string to the text buffer, trimming whitespaces as needed */
-  def append(  cs:Seq[Char] ):TextBuffer = {
-    for( val c <- cs ) {
-      if( Utility.isSpace( c ) )
-        appendSpace;
+  /** Appends this string to the text buffer, trimming whitespaces as needed.
+   *
+   *  @param  cs ...
+   *  @return ...
+   */
+  def append(cs: Seq[Char]): TextBuffer = {
+    for (val c <- cs) {
+      if (Utility.isSpace(c))
+        appendSpace
       else
-        appendChar( c )
+        appendChar(c)
     }
     this
   }
 
-  /** returns an empty sequence if text is only whitespace */
-  def toText:Seq[Text] = {
-    var len = sb.length(); /* invariant */
-    if( len == 0 ) return Nil;
+  /** Returns an empty sequence if text is only whitespace.
+   *
+   *  @return the text without whitespaces.
+   */
+  def toText: Seq[Text] = {
+    var len = sb.length() /* invariant */
+    if (len == 0) return Nil
 
-    if( Utility.isSpace( sb.charAt( len - 1 ) )) {
-      len = len - 1;
-      sb.setLength( len )
+    if (Utility.isSpace(sb.charAt(len - 1))) {
+      len = len - 1
+      sb.setLength(len)
     }
-    if( len == 0 ) return Nil;
+    if (len == 0) return Nil
 
-    List( Text( sb.toString() ) );
+    List(Text(sb.toString()))
   }
 
 }