rewrote handling of Scala comments in DocGenera...

rewrote handling of Scala comments in DocGenerator.scala improved Scala
comments in library and compiler source files added test in method
'apply' of class collection.immutable.Queue

10 files changed, 312 insertions, 207 deletions

diff --git a/src/compiler/scala/tools/ant/ScalaTool.scala b/src/compiler/scala/tools/ant/ScalaTool.scala
index a159d4fed8..01920985bb 100644
--- a/src/compiler/scala/tools/ant/ScalaTool.scala
+++ b/src/compiler/scala/tools/ant/ScalaTool.scala
@@ -23,30 +23,35 @@ package scala.tools.ant {
                                     SourceFileScanner}
   import org.apache.tools.ant.types.{EnumeratedAttribute, Reference}
 
-  /** An Ant task that generates a SH or BAT script to execute a Scala program.
-    * This task can take the following parameters as attributes:<ul>
-    *  <li>file (mandatory),</li>
-    *  <li>name,</li>
-    *  <li>class (mandatory),</li>
-    *  <li>platforms,</li>
-    *  <li>version,</li>
-    *  <li>copyright,</li>
-    *  <li>bootclasspath,</li>
-    *  <li>extclasspath,</li>
-    *  <li>properties,</li>
-    *  <li>javaflags,</li>
-    *  <li>toolflags,</li>
-    *  <li>genericfile.</li></ul>
-    *
-    * @author Gilles Dubochet */
+  /** <p>
+   *    An Ant task that generates a shell or batch script to execute a
+   *    <a href="http://scala.epfl.ch/" target="_top">Scala</a> program.
+   *    This task can take the following parameters as attributes:
+   *  </p><ul>
+   *  <li>file (mandatory),</li>
+   *  <li>name,</li>
+   *  <li>class (mandatory),</li>
+   *  <li>platforms,</li>
+   *  <li>version,</li>
+   *  <li>copyright,</li>
+   *  <li>bootclasspath,</li>
+   *  <li>extclasspath,</li>
+   *  <li>properties,</li>
+   *  <li>javaflags,</li>
+   *  <li>toolflags,</li>
+   *  <li>genericfile.</li></ul>
+   *
+   * @author  Gilles Dubochet
+   * @version 1.0
+   */
   class ScalaTool extends MatchingTask {
 
     /** The unique Ant file utilities instance to use in this task. */
     private val fileUtils = FileUtils.newFileUtils()
 
-/******************************************************************************\
+/*============================================================================*\
 **                             Ant user-properties                            **
-\******************************************************************************/
+\*============================================================================*/
 
     abstract class PermissibleValue {
       val values: List[String]
@@ -93,22 +98,31 @@ package scala.tools.ant {
       * be set when a main class is defined */
     private var toolFlags: String = ""
 
-/******************************************************************************\
+/*============================================================================*\
 **                             Properties setters                             **
-\******************************************************************************/
+\*============================================================================*/
 
-    /** Sets the file attribute. Used by Ant.
-      * @param input The value of <code>file</code>. */
+    /** Sets the file attribute.
+     *  Used by <a href="http://ant.apache.org/" target="_top">Ant</a>.
+     *
+     *  @param input The value of <code>file</code>.
+     */
     def setFile(input: File) =
       file = Some(input)
 
-    /** Sets the file attribute. Used by Ant.
-      * @param input The value of <code>file</code>. */
+    /** Sets the file attribute.
+     *  Used by <a href="http://ant.apache.org/" target="_top">Ant</a>.
+     *
+     *  @param input The value of <code>file</code>.
+     */
     def setName(input: String) =
       name = Some(input)
 
-    /** Sets the main class attribute. Used by Ant.
-      * @param input The value of <code>mainClass</code>. */
+    /** Sets the main class attribute.
+     *  Used by <a href="http://ant.apache.org/" target="_top">Ant</a>.
+     *
+     *  @param input The value of <code>mainClass</code>.
+     */
     def setClass(input: String) =
       mainClass = Some(input)
 
@@ -126,28 +140,43 @@ package scala.tools.ant {
       }
     }
 
-    /** Sets the version attribute. Used by Ant.
-      * @param input The value of <code>version</code>. */
+    /** Sets the version attribute.
+     *  Used by <a href="http://ant.apache.org/" target="_top">Ant</a>.
+     *
+     *  @param input The value of <code>version</code>.
+     */
     def setVersion(input: String) =
       version = input
 
-    /** Sets the copyright attribute. Used by Ant.
-      * @param input The value of <code>copyright</code>. */
+    /** Sets the copyright attribute.
+     *  Used by <a href="http://ant.apache.org/" target="_top">Ant</a>.
+     *
+     *  @param input The value of <code>copyright</code>.
+     */
     def setCopyright(input: String) =
       copyright = input
 
-    /** Sets the boot classpath attribute. Used by Ant.
-      * @param input The value of <code>bootclasspath</code>. */
+    /** Sets the boot classpath attribute.
+     *  Used by <a href="http://ant.apache.org/" target="_top">Ant</a>.
+     *
+     *  @param input The value of <code>bootclasspath</code>.
+     */
     def setBootclasspath(input: String) =
       bootclasspath = bootclasspath ::: List.fromArray(input.split(":"))
 
-    /** Sets the extension classpath attribute. Used by Ant.
-      * @param input The value of <code>extclasspath</code>. */
+    /** Sets the extension classpath attribute.
+     *  Used by <a href="http://ant.apache.org/" target="_top">Ant</a>.
+     *
+     *  @param input The value of <code>extclasspath</code>.
+     */
     def setExtclasspath(input: String) =
       extclasspath = extclasspath ::: List.fromArray(input.split(":"))
 
-    /** Sets the properties attribute. Used by Ant.
-      * @param input The value for <code>properties</code>. */
+    /** Sets the properties attribute.
+     *  Used by <a href="http://ant.apache.org/" target="_top">Ant</a>.
+     *
+     *  @param input The value for <code>properties</code>.
+     */
     def setProperties(input: String) = {
       properties = List.fromArray(input.split(",")).flatMap { s: String =>
         val st = s.trim(); val stArray = st.split("=", 2)
@@ -157,19 +186,25 @@ package scala.tools.ant {
       }
     }
 
-    /** Sets the version attribute. Used by Ant.
-      * @param input The value of <code>version</code>. */
+    /** Sets the version attribute.
+     *  Used by <a href="http://ant.apache.org/" target="_top">Ant</a>.
+     *
+     *  @param input The value of <code>version</code>.
+     */
     def setJavaflags(input: String) =
       javaFlags = input
 
-    /** Sets the version attribute. Used by Ant.
-      * @param input The value of <code>version</code>. */
+    /** Sets the version attribute.
+     *  Used by <a href="http://ant.apache.org/" target="_top">Ant</a>.
+     *
+     *  @param input The value of <code>version</code>.
+     */
     def setToolflags(input: String) =
       toolFlags = input
 
-/******************************************************************************\
+/*============================================================================*\
 **                             Properties getters                             **
-\******************************************************************************/
+\*============================================================================*/
 
     /** Gets the value of the file attribute in a Scala-friendly form.
       * @returns The file as a file. */
@@ -206,9 +241,9 @@ package scala.tools.ant {
         case Pair(name,value) => "-D" + name + "=\"" + value + "\""
       }).mkString("", " ", "")
 
-/******************************************************************************\
+/*============================================================================*\
 **                       Compilation and support methods                      **
-\******************************************************************************/
+\*============================================================================*/
 
     /** Generates a build error. Error location will be the current task in the
       * ant file.
@@ -289,9 +324,9 @@ package scala.tools.ant {
     }
 
 
-/******************************************************************************\
+/*============================================================================*\
 **                           The big execute method                           **
-\******************************************************************************/
+\*============================================================================*/
 
     /** Performs the compilation. */
     override def execute() = {
diff --git a/src/compiler/scala/tools/nsc/ScriptRunner.scala b/src/compiler/scala/tools/nsc/ScriptRunner.scala
index 9f51af40e3..3d7ec1d214 100644
--- a/src/compiler/scala/tools/nsc/ScriptRunner.scala
+++ b/src/compiler/scala/tools/nsc/ScriptRunner.scala
@@ -6,25 +6,27 @@
 
 package scala.tools.nsc
 
-import java.io._
-import java.util.jar._
+import java.io.{BufferedReader, File, FileInputStream, FileOutputStream,
+                FileReader, InputStreamReader, PrintWriter}
+import java.util.jar.{JarEntry, JarOutputStream}
 import java.lang.reflect.InvocationTargetException
-import scala.tools.nsc.util._
-import scala.tools.nsc.io._
+
+import scala.tools.nsc.io.PlainFile
 import scala.tools.nsc.reporters.ConsoleReporter
+import scala.tools.nsc.util.{CompoundSourceFile, SourceFile, SourceFileFragment}
 
 /** An object that runs Scala code in script files.
  *
- *  For example, here is a complete Scala script on Unix:
- *
+ *  <p>For example, here is a complete Scala script on Unix:</pre>
+ *  <pre>
  *    #!/bin/sh
  *    exec scala "$0" "$@"
  *    !#
  *    Console.println("Hello, world!")
  *    argv.toList foreach Console.println
- *
- * And here is a batch file example on Windows XP:
- *
+ *  </pre>
+ *  <p>And here is a batch file example on Windows XP:</p>
+ *  <pre>
  *    ::#!
  *    @echo off
  *    call scala %0 %*
@@ -32,14 +34,18 @@ import scala.tools.nsc.reporters.ConsoleReporter
  *    ::!#
  *    Console.println("Hello, world!")
  *    argv.toList foreach Console.println
+ *  </pre>
  *
- * TODO: It would be better if error output went to stderr instead
- * of stdout....
+ *  @author  Lex Spoon
+ *  @version 1.0, 15/05/2006
+ *  @todo    It would be better if error output went to stderr instead
+ *           of stdout...
  */
 object ScriptRunner {
+
   /** Choose a jar filename to hold the compiled version
-    * of a script
-    */
+   * of a script
+   */
   private def jarFileFor(scriptFile: String): File = {
     val filename =
       if (scriptFile.matches(".*\\.[^.\\\\/]*"))
@@ -50,9 +56,9 @@ object ScriptRunner {
     new File(filename)
   }
 
-  /** Try to create a jar out of all the contents
-    * of a directory.
-    */
+  /** Try to create a jar file out of all the contents
+   *  of the directory <code>sourcePath</code>.
+   */
   private def tryMakeJar(jarFile: File, sourcePath: File) = {
     try {
       val jarFileStream = new FileOutputStream(jarFile)
@@ -121,8 +127,12 @@ object ScriptRunner {
   }
 
   /** Wrap a script file into a runnable object named
-    * scala.scripting.Main .
-    */
+   *  <code>scala.scripting.Main</code>.
+   *
+   *  @param filename      ...
+   *  @param getSourceFile ...
+   *  @return              ...
+   */
   def wrappedScript(filename: String, getSourceFile: PlainFile => SourceFile): SourceFile = {
     val preamble =
       new SourceFile("<script preamble>",
@@ -143,7 +153,12 @@ object ScriptRunner {
     new CompoundSourceFile(preamble, middle, end)
   }
 
-  /** Compile a script using the fsc compilation deamon */
+  /** Compile a script using the fsc compilation deamon.
+   *
+   *  @param settings     ...
+   *  @param scriptFileIn ...
+   *  @return             ...
+   */
   private def compileWithDaemon(
       settings: GenericRunnerSettings,
       scriptFileIn: String): Boolean =
@@ -272,8 +287,12 @@ object ScriptRunner {
   }
 
   /** Run a script file with the specified arguments and compilation
-    * settings.
-    */
+   *  settings.
+   *
+   *  @param settings   ...
+   *  @param scriptFile ...
+   *  @param scriptArgs ...
+   */
   def runScript(
       settings: GenericRunnerSettings,
       scriptFile: String,
diff --git a/src/compiler/scala/tools/nsc/ast/parser/Parsers.scala b/src/compiler/scala/tools/nsc/ast/parser/Parsers.scala
index b71446ffc0..30ba3a7c98 100644
--- a/src/compiler/scala/tools/nsc/ast/parser/Parsers.scala
+++ b/src/compiler/scala/tools/nsc/ast/parser/Parsers.scala
@@ -13,33 +13,40 @@ import Tokens._
 
 //todo verify when stableId's should be just plain qualified type ids
 
-/** Performs the following context-free rewritings:
- *  (1) Places all pattern variables in Bind nodes. In a pattern, for identifiers `x':
+/** <p>Performs the following context-free rewritings:</p>
+ *  <ol>
+ *    <li>
+ *      Places all pattern variables in Bind nodes. In a pattern, for
+ *      identifiers <code>x</code>:<pre>
  *                 x  => x @ _
- *               x:T  => x @ (_ : T)
+ *               x:T  => x @ (_ : T)</pre>
+ *    </li>
+ *    <li>Removes pattern definitions (PatDef's) as follows:
+ *      If pattern is a simple (typed) identifier:<pre>
+ *        <b>val</b> x = e     ==>  <b>val</b> x = e
+ *        <b>val</b> x: T = e  ==>  <b>val</b> x: T = e</pre>
  *
- *  (2) Removes pattern definitions (PatDef's) as follows:
- *      If pattern is a simple (typed) identifier:
- *        val x = e     ==>  val x = e
- *        val x: T = e  ==>  val x: T = e
+ *      if there are no variables in pattern<pre>
+ *        <b>val</b> p = e  ==>  e match (case p => ())</pre>
  *
- *      if there are no variables in pattern
- *        val p = e  ==>  e.match (case p => ())
+ *      if there is exactly one variable in pattern<pre>
+ *        <b>val</b> x_1 = e <b>match</b> (case p => (x_1))</pre>
  *
- *      if there is exactly one variable in pattern
- *        val x_1 = e.match (case p => (x_1))
- *
- *      if there is more than one variable in pattern
- *        val p = e  ==>  private synthetic val t$ = e.match (case p => (x_1, ..., x_N))
- *                        val x_1 = t$._1
+ *      if there is more than one variable in pattern<pre>
+ *        <b>val</b> p = e  ==>  <b>private synthetic val</b> t$ = e <b>match</b> (case p => (x_1, ..., x_N))
+ *                        <b>val</b> x_1 = t$._1
  *                        ...
- *                        val x_N = t$._N
- *
- *  (3) Removes function types as follows:
- *        (argtpes) => restpe   ==>   scala.Function_n[argtpes, restpe]
- *
- *  (4) Wraps naked case definitions in a match as follows:
- *        { cases }   ==>   (x => x.match {cases}), except when already argument to match
+ *                        <b>val</b> x_N = t$._N</pre>
+ *    </li>
+ *    <li>
+ *       Removes function types as follows:<pre>
+ *        (argtpes) => restpe   ==>   scala.Function_n[argtpes, restpe]</pre>
+ *    </li>
+ *    <li>
+ *      Wraps naked case definitions in a match as follows:<pre>
+ *        { cases }   ==>   (x => x.match {cases})<span style="font-family:normal;">, except when already argument to match</span></pre>
+ *    </li>
+ *  </ol>
  */
 trait Parsers requires SyntaxAnalyzer {
 
diff --git a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
index 17d1632392..965a77d4bf 100644
--- a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
+++ b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
@@ -8,6 +8,7 @@ package scala.tools.nsc.doc
 
 import java.io.{File,FileOutputStream,FileWriter}
 import java.util.StringTokenizer
+import java.util.regex.Pattern
 
 import scala.collection.immutable._
 import scala.tools.nsc._
@@ -662,6 +663,7 @@ abstract class DocGenerator extends Models {
         case "see"     => "See"
         case "since"   => "Since"
         case "throws"  => "Throws"
+        case "todo"    => "Todo"
         case "version" => "Version"
         case _ => name
       }) + ":")
@@ -676,24 +678,27 @@ abstract class DocGenerator extends Models {
     comment0 = comment0.substring(JDOC_START.length())
     assert(comment0 endsWith JDOC_END)
     comment0 = comment0.substring(0, comment0.length() - JDOC_END.length())
-    var idx = 0
-    while (idx != -1) {
-      idx = comment0.indexOf('*', idx)
-      if (idx != -1)
-        comment0 = comment0.substring(0, idx) +
-          comment0.substring(idx + 1, comment0.length());
-    }
-    val tokenizer = new StringTokenizer(comment0, "@")
-    val body = tokenizer.nextToken()
-    var attributes: List[Tuple2[String,String]] = Nil
-    if (!isShort) while (tokenizer.hasMoreElements()) {
-      val attr = tokenizer.nextToken()
-      val div = attr.indexOf(' ')
-      val tuple =
-        if (div == -1) new Tuple2(attr,"")
-        else new Tuple2(attr.substring(0, div), attr.substring(div + 1, attr.length()))
-      attributes = attributes ::: (tuple :: Nil)
+    val buf = new StringBuffer
+    var attributes: List[Triple[String, String, String]] = Nil
+    val tok = new StringTokenizer(comment0, LINE_SEPARATOR)
+    val pat1 = Pattern.compile("[ \t]*@(author|return|see|since|throws|todo|version)[ \t]+(.*)")
+    val pat2 = Pattern.compile("[ \t]*@(param)[ \t]+(\\p{Alnum}*)[ \t]+(.*)")
+    while (tok.hasMoreTokens) {
+      val s = tok.nextToken.replaceFirst("\\p{Space}?\\*", "")
+      val mat1 = pat1.matcher(s)
+      attributes = if (mat1.matches)
+        attributes ::: List(Triple(mat1.group(1), null, mat1.group(2)))
+      else {
+         val mat2 = pat2.matcher(s)
+         if (mat2.matches)
+           attributes ::: List(Triple(mat2.group(1), mat2.group(2), mat2.group(3)))
+         else {
+           buf.append(s + LINE_SEPARATOR)
+           attributes
+         }
+      }
     }
+    val body = buf.toString
     if (isShort) <span>{parse(body)}</span>;
     else <span><dl><dd>{parse(body)}</dd></dl><dl>
     { {
@@ -701,7 +706,11 @@ abstract class DocGenerator extends Models {
         <dt style="margin:10px 0 0 20px;">
           {tag(attr._1)}
         </dt>
-        <dd>{(parse(attr._2))}</dd>;
+        <dd> {
+          if (attr._2 == null) NodeSeq.Empty
+          else <code>{attr._2 + " - "}</code>
+        } {(parse(attr._3))}
+        </dd>;
     } } </dl></span>;
   }
 
diff --git a/src/library/scala/Attribute.scala b/src/library/scala/Attribute.scala
index 192e6d6bec..ed596f27b7 100644
--- a/src/library/scala/Attribute.scala
+++ b/src/library/scala/Attribute.scala
@@ -18,6 +18,7 @@ package scala
  *      <a href="cloneable.html" target="contentFrame">cloneable</a>,
  *      <a href="remote.html" target="contentFrame">remote</a>,
  *      <a href="serializable.html" target="contentFrame">serializable</a>,
+ *      <a href="SerialVersionUID.html" target="contentFrame">SerialVersionUID</a>,
  *      <a href="throws.html" target="contentFrame">throws</a>,
  *      <a href="transient.html" target="contentFrame">transient</a>,
  *      <a href="volatile.html" target="contentFrame">volatile</a>
diff --git a/src/library/scala/Stream.scala b/src/library/scala/Stream.scala
index 07954ed08c..2da67a1ea5 100644
--- a/src/library/scala/Stream.scala
+++ b/src/library/scala/Stream.scala
@@ -127,15 +127,15 @@ object Stream {
  * <p>The class <code>Stream</code> implements lazy lists where elements
  * are only evaluated when they are needed. Here is an example:</p>
  * <pre>
- * <b>object</b> Main <b>with</b> Application {
+ * <b>object</b> Main <b>extends</b> Application {
  *
  *   <b>def</b> from(n: Int): Stream[Int] =
- *     Stream.cons(n, from(n + 1));
+ *     Stream.cons(n, from(n + 1))
  *
  *   <b>def</b> sieve(s: Stream[Int]): Stream[Int] =
- *     Stream.cons(s.head, sieve(s.tail filter { x => x % s.head != 0 }));
+ *     Stream.cons(s.head, sieve(s.tail filter { x => x % s.head != 0 }))
  *
- *   <b>def</b> primes = sieve(from(2));
+ *   <b>def</b> primes = sieve(from(2))
  *
  *   primes take 10 print
  * }
diff --git a/src/library/scala/collection/immutable/Queue.scala b/src/library/scala/collection/immutable/Queue.scala
index 1329a44e03..8e1730c74f 100644
--- a/src/library/scala/collection/immutable/Queue.scala
+++ b/src/library/scala/collection/immutable/Queue.scala
@@ -36,13 +36,19 @@ class Queue[+A](elem: A*) extends Seq[A] {
   /** Returns the <code>n</code>-th element of this queue.
    *  The first element is at position 0.
    *
-   *  @param n index of the element to return
-   *  @return the element at position <code>n</code> in this list.
-   *  @throws java.lang.RuntimeException if the list is too short.
+   *  @param  n index of the element to return
+   *  @return   the element at position <code>n</code> in this queue.
+   *  @throws   <code>java.lang.Error</code> if the queue is too short.
    */
-  def apply(n: Int): A =
-    if (n < out.length) out.apply(n)
-    else in.reverse.apply(n - out.length)
+  def apply(n: Int): A = {
+    val len = out.length
+    if (n < len) out.apply(n)
+    else {
+      val m = n - len
+      if (m < in.length) in.reverse.apply(m)
+      else error("index out of range")
+    }
+  }
 
   /** Returns the elements in the list as an iterator
    */
diff --git a/src/library/scala/collection/immutable/Tree.scala b/src/library/scala/collection/immutable/Tree.scala
index 81a7fa61fb..19644c797c 100644
--- a/src/library/scala/collection/immutable/Tree.scala
+++ b/src/library/scala/collection/immutable/Tree.scala
@@ -41,23 +41,26 @@ package scala.collection.immutable
 
 /** General Balanced Trees - highly efficient functional dictionaries.
  *
- *  An efficient implementation of Prof. Arne Andersson's General
+ *  <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/>
- *  This implementation does not balance the trees after deletions.
+ *  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/>
- *  The tree consists of entries conatining a key with an order.
- *  <p/>
- *  When instanciating the tree an order for the keys has to be
- *  supplied.
+ *  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>
+ *  <dl>
+ *    <dt><b>Direct Known Subclasses:</b></dt>
+ *    <dd>
+ *      <a href="TreeMap.html" target="contentFrame">TreeMap</a>,
+ *      <a href="TreeSet.html" target="contentFrame">TreeSet</a>
+ *   </dd>
+ *  </dl>
  *
- *  @author  Erik Stenman
- *  @author  Michel Schinz
+ *  @author  Erik Stenman, Michel Schinz
  *  @version 1.1, 2005-01-20
  */
 
@@ -91,33 +94,37 @@ abstract class Tree[A <% Ordered[A], B]() extends AnyRef {
   protected type aNode = GBTree[A,B]
 
   /** The nodes in the tree.
-  */
+   */
   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>
-  **
-  */
+   *   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>
+   *
+   */
   protected def New(sz: Int, t: aNode): This
 
   /** The size of the tree, returns 0 (zero) if the tree is empty.
-  **  @Returns The number of nodes in the tree as an integer.
-  **/
+   *
+   *  @return The number of nodes in the tree as an integer.
+   */
   def size: Int = 0
 
-  /**
-  *   A new tree with the entry added is returned,
-  *   assuming that key is <em>not</em> in the tree.
-  */
+  /** A new tree with the entry added is returned,
+   *  assuming that key is <em>not</em> in the tree.
+   *
+   *  @param key   ...
+   *  @param entry ...
+   *  @return      ...
+   */
   protected def add(key: A, entry: B): This = {
     val newSize = size + 1
     New(newSize, tree.insert(key, entry, newSize * newSize).node)
@@ -133,14 +140,22 @@ abstract class Tree[A <% Ordered[A], B]() extends AnyRef {
     else
       add(key,entry)
 
-  /** Removes the key from the tree. */
+  /** Removes the key from the tree.
+   *
+   *  @param key ...
+   *  @return    ...
+   */
   protected def deleteAny(key: A): This =
     if (tree.isDefinedAt(key))
       delete(key)
     else
       getThis
 
-  /** Removes the key from the tree, assumimg that key is present. */
+  /** Removes the key from the tree, assumimg that key is present.
+   *
+   *  @param key ...
+   *  @return    ...
+   */
   private def delete(key: A): This =
     New(size - 1, tree.delete(key))
 
@@ -185,6 +200,10 @@ protected abstract class InsertTree[A <% Ordered[A],B]() extends AnyRef {
   def node: GBTree[A,B]
 }
 
+/**
+ *  <code>ITree</code> is an internal class used by
+ *  <a href="Tree.html" target="contentFrame"><code>Tree</code></a>.
+ */
 private case class ITree[A <% Ordered[A],B](t: GBTree[A,B])
              extends InsertTree[A,B] {
   def insertLeft(key: A, value: B, bigger: GBTree[A,B]) =
@@ -194,6 +213,10 @@ private case class ITree[A <% Ordered[A],B](t: GBTree[A,B])
   def node = t
 }
 
+/**
+ *  <code>INode</code> is an internal class used by
+ *  <a href="Tree.html" target="contentFrame"><code>Tree</code></a>.
+ */
 private case class INode[A <% Ordered[A],B](t1: GBTree[A,B],
                                             height: int,
                                             size: int)
diff --git a/src/library/scala/util/regexp/WordExp.scala b/src/library/scala/util/regexp/WordExp.scala
index e2111e3d27..e4cfbe0dfb 100644
--- a/src/library/scala/util/regexp/WordExp.scala
+++ b/src/library/scala/util/regexp/WordExp.scala
@@ -12,25 +12,25 @@
 package scala.util.regexp
 
 /** This class provides regular word expressions. Users have to instantiate
- *  type member <code>_regexpT &lt;: RegExp</code< (from class <code>Base</code>)
+ *  type member <code>_regexpT &lt;: RegExp</code> (from class <code>Base</code>)
  *  and a type member <code>_labelT &lt;: Label</code>.
  *  Here is a little example:
  *  <pre>
-  import scala.util.regexp._
-  import scala.util.automata._
-  object MyLang extends WordExp {
-    type _regexpT = RegExp
-    type _labelT = MyChar
-
-    case class MyChar(c:Char) extends Label
-  }
-  import MyLang._
-  // (a* | b)*
-  val rex = Star(Alt(Star(Letter(MyChar('a'))),Letter(MyChar('b'))))
-  object MyBerriSethi extends WordBerrySethi {
-    override val lang = MyLang
-  }
-  val nfa = MyBerriSethi.automatonFrom(Sequ(rex),1)
+ *  <b>import</b> scala.util.regexp._
+ *  <b>import</b> scala.util.automata._
+ *  <b>object</b> MyLang <b>extends</b> WordExp {
+ *    <b>type</b> _regexpT = RegExp
+ *    <b>type</b> _labelT = MyChar
+ *
+ *    <b>case class</b> MyChar(c:Char) <b>extends</b> Label
+ *  }
+ *  <b>import</b> MyLang._
+ *  // (a* | b)*
+ *  <b>val</b> rex = Star(Alt(Star(Letter(MyChar('a'))),Letter(MyChar('b'))))
+ *  <b>object</b> MyBerriSethi <b>extends</b> WordBerrySethi {
+ *    <b>override val</b> lang = MyLang
+ *  }
+ *  <b>val</b> nfa = MyBerriSethi.automatonFrom(Sequ(rex), 1)
  *  </pre>
  *
  *  @author  Burak Emir
diff --git a/src/library/scala/xml/factory/LoggedNodeFactory.scala b/src/library/scala/xml/factory/LoggedNodeFactory.scala
index 4f472bd488..e6d3791bff 100644
--- a/src/library/scala/xml/factory/LoggedNodeFactory.scala
+++ b/src/library/scala/xml/factory/LoggedNodeFactory.scala
@@ -9,51 +9,56 @@
 // $Id$
 
 
-package scala.xml.factory;
-
-
-/** This class logs what the nodefactory is actually doing.
-If you want to see what happens during loading, use it like this:
-object testLogged with Application {
-
-  val x = new scala.xml.nobinding.NoBindingFactoryAdapter
-            with scala.xml.LoggedNodeFactory[scala.xml.Elem]()
-            with scala.util.logging.ConsoleLogger;
-
-  Console.println("Start");
-
-  val doc = x.loadXML(new org.xml.sax.InputSource("http://lamp.epfl.ch/~buraq"));
-
-  Console.println("End");
-
-  Console.println(doc);
-}
-
-*/
+package scala.xml.factory
+
+
+/** <p>
+ *    This class logs what the nodefactory is actually doing.
+ *    If you want to see what happens during loading, use it like this:
+ *  </p><pre>
+ *  <b>object</b> testLogged <b>extends</b> Application {
+ *
+ *    <b>val</b> x = <b>new</b> scala.xml.nobinding.NoBindingFactoryAdapter
+ *          <b>with</b> scala.xml.LoggedNodeFactory[scala.xml.Elem]()
+ *          <b>with</b> scala.util.logging.ConsoleLogger;
+ *
+ *    Console.println("Start");
+ *
+ *    <b>val</b> doc = x.loadXML(new org.xml.sax.InputSource("http://lamp.epfl.ch/~buraq"));
+ *
+ *    Console.println("End");
+ *
+ *    Console.println(doc);
+ *  }</pre>
+ *
+ *  @author  Burak Emir
+ *  @version 1.0
+ */
 abstract class LoggedNodeFactory[A <: Node]
 extends NodeFactory[A]
 with scala.util.logging.Logged {
 
   // configuration values;
-  val logNode      = true;
-  val logText      = false;
-  val logComment   = false;
-  val logProcInstr = false;
-
-  final val NONE  = 0;
-  final val CACHE = 1;
-  final val FULL  = 2;
+  val logNode      = true
+  val logText      = false
+  val logComment   = false
+  val logProcInstr = false
+
+  final val NONE  = 0
+  final val CACHE = 1
+  final val FULL  = 2
   /** 0 = no loggging, 1 = cache hits, 2 = detail */
-  val logCompressLevel  = 1;
+  val logCompressLevel  = 1
 
   // methods of NodeFactory
 
   /** logged version of makeNode method */
-  override def makeNode(pre:String, label:String, attrSeq:MetaData, scope: NamespaceBinding, children:Seq[Node]): A = {
-    if(logNode)
+  override def makeNode(pre: String, label: String, attrSeq: MetaData,
+                        scope: NamespaceBinding, children: Seq[Node]): A = {
+    if (logNode)
       log("[makeNode for "+label+"]");
 
-    val hash = Utility.hashCode(pre, label, attrSeq.hashCode(), scope.hashCode(), children) ;
+    val hash = Utility.hashCode(pre, label, attrSeq.hashCode(), scope.hashCode(), children)
 
     /*
     if(logCompressLevel >= FULL) {
@@ -63,28 +68,28 @@ with scala.util.logging.Logged {
       log(" children :"+children+" hash "+children.hashCode());
     }
     */
-    if(!cache.get( hash ).isEmpty && (logCompressLevel >= CACHE))
+    if (!cache.get( hash ).isEmpty && (logCompressLevel >= CACHE))
       log("[cache hit !]");
 
-    super.makeNode(pre, label, attrSeq, scope, children);
+    super.makeNode(pre, label, attrSeq, scope, children)
   }
 
   override def makeText(s: String) = {
-    if(logText)
+    if (logText)
       log("[makeText:\""+s+"\"]");
-    super.makeText( s );
+    super.makeText(s)
   }
 
   override def makeComment(s: String): Seq[Comment] = {
-    if(logComment)
+    if (logComment)
       log("[makeComment:\""+s+"\"]");
-    super.makeComment( s );
+    super.makeComment(s)
   }
 
   override def makeProcInstr(t: String, s: String): Seq[ProcInstr] = {
-    if(logProcInstr)
+    if (logProcInstr)
       log("[makeProcInstr:\""+t+" "+ s+"\"]");
-    super.makeProcInstr(t,s);
+    super.makeProcInstr(t, s)
   }
 
 }