fixed multiline descriptions in scaladoc tags

4 files changed, 78 insertions, 63 deletions

diff --git a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
index 965a77d4bf..a13256f009 100644
--- a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
+++ b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
@@ -11,6 +11,7 @@ import java.util.StringTokenizer
 import java.util.regex.Pattern
 
 import scala.collection.immutable._
+import scala.collection.mutable.ListBuffer
 import scala.tools.nsc._
 import scala.tools.nsc.models._
 import scala.tools.nsc.symtab.Flags
@@ -350,16 +351,16 @@ abstract class DocGenerator extends Models {
     }
 
     def fullComment(mmbr: HasTree): NodeSeq =
-      if (comments contains mmbr.tree.symbol)
-        comment(comments(mmbr.tree.symbol), false)
-      else
-        NodeSeq.Empty
+      comments.get(mmbr.tree.symbol) match {
+        case Some(text) => comment(text, false)
+        case None => NodeSeq.Empty
+      }
 
     def shortComment(mmbr: HasTree): NodeSeq =
-      if (comments contains mmbr.tree.symbol)
-        comment(comments(mmbr.tree.symbol), true)
-      else
-        NodeSeq.Empty
+      comments.get(mmbr.tree.symbol) match {
+        case Some(text) => comment(text, true)
+        case None => NodeSeq.Empty
+      }
 
     def ifT(cond: Boolean, nodes: NodeSeq) =
       if (cond) nodes else NodeSeq.Empty
@@ -524,7 +525,7 @@ abstract class DocGenerator extends Models {
             topLevel = topLevel.update(sym, organize0(mmbr, topLevel(sym)))
           }
         case _ =>
-          throw new Error("unknown: " + mmbr.tree + " " + mmbr.tree.getClass())
+          error("unknown: " + mmbr.tree + " " + mmbr.tree.getClass())
       }
     }
 
@@ -593,7 +594,7 @@ abstract class DocGenerator extends Models {
       override def hasBody = false
     }
     val rsrcdir = "scala/tools/nsc/doc/".replace('/', File.separatorChar)
-    for (val base <- "style.css" :: "script.js" :: Nil) {
+    for (val base <- List("style.css", "script.js")) {
       val input = loader.getResourceAsStream(rsrcdir + base)
       if (input != null) {
         val file  = new File(outdir + File.separator + base)
@@ -602,15 +603,13 @@ abstract class DocGenerator extends Models {
         val bytes = new Array[byte](1024)
         while (!break) {
           val read = input.read(bytes)
-          if (read == -1) {
-            break = true
-          } else {
-            output.write(bytes, 0, read)
-          }
+          if (read == -1) break = true
+          else output.write(bytes, 0, read)
         }
         input.close()
         output.close()
-      }
+      } else
+        error("Resource file '" + base + "' not found")
     }
   }
 
@@ -660,7 +659,7 @@ abstract class DocGenerator extends Models {
         case "author"  => "Author"
         case "param"   => "Parameters"
         case "return"  => "Returns"
-        case "see"     => "See"
+        case "see"     => "See Also"
         case "since"   => "Since"
         case "throws"  => "Throws"
         case "todo"    => "Todo"
@@ -679,37 +678,42 @@ abstract class DocGenerator extends Models {
     assert(comment0 endsWith JDOC_END)
     comment0 = comment0.substring(0, comment0.length() - JDOC_END.length())
     val buf = new StringBuffer
-    var attributes: List[Triple[String, String, String]] = Nil
-    val tok = new StringTokenizer(comment0, LINE_SEPARATOR)
+    type AttrDescr = Triple[String, String, StringBuffer]
+    val attributes = new ListBuffer[AttrDescr]
+    var attr: AttrDescr = null
     val pat1 = Pattern.compile("[ \t]*@(author|return|see|since|throws|todo|version)[ \t]+(.*)")
     val pat2 = Pattern.compile("[ \t]*@(param)[ \t]+(\\p{Alnum}*)[ \t]+(.*)")
+    val tok = new StringTokenizer(comment0, LINE_SEPARATOR)
     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
-         }
+      if (mat1.matches) {
+        attr = Triple(mat1.group(1), null, new StringBuffer(mat1.group(2)))
+        attributes += attr
+      } else {
+        val mat2 = pat2.matcher(s)
+        if (mat2.matches) {
+          attr = Triple(mat2.group(1), mat2.group(2), new StringBuffer(mat2.group(3)))
+          if (isShort)
+            attributes += attr
+        } else if (attr != null)
+          attr._3.append(s + LINE_SEPARATOR)
+        else
+          buf.append(s + LINE_SEPARATOR)
       }
     }
     val body = buf.toString
     if (isShort) <span>{parse(body)}</span>;
     else <span><dl><dd>{parse(body)}</dd></dl><dl>
     { {
-      for (val attr <- attributes) yield
+      for (val attr <- attributes.toList) yield
         <dt style="margin:10px 0 0 20px;">
           {tag(attr._1)}
         </dt>
         <dd> {
           if (attr._2 == null) NodeSeq.Empty
           else <code>{attr._2 + " - "}</code>
-        } {(parse(attr._3))}
+        } {(parse(attr._3.toString))}
         </dd>;
     } } </dl></span>;
   }
diff --git a/src/compiler/scala/tools/nsc/io/AbstractFile.scala b/src/compiler/scala/tools/nsc/io/AbstractFile.scala
index 1faa3c2382..8753396e16 100644
--- a/src/compiler/scala/tools/nsc/io/AbstractFile.scala
+++ b/src/compiler/scala/tools/nsc/io/AbstractFile.scala
@@ -44,26 +44,31 @@ object AbstractFile {
 }
 
 /**
- * This class and its children serve to unify handling of files and
- * directories. These files and directories may or may not have some
- * real counter part within the file system. For example, some file
- * handles reference files within a zip archive or virtual ones
- * that exist only in memory.
- *
- * Every abstract file has a path (i.e. a full name) and a name
- * (i.e. a short name) and may be backed by some real File. There are
- * two different kinds of abstract files: regular files and
- * directories. Regular files may be read and have a last modification
- * time. Directories may list their content and look for subfiles with
- * a specified name or path and of a specified kind.
- *
- * bq: The interface allows to access the content as bytes and as chars.
- * In fact, only the ClassFileParser should access bytes, because
- * only there we know that the charset of the file is UTF-8. For
- * all other cases, the global.settings.encoding.value must be
- * respected. @todo it would be better if reading chars from sources
- * was exclusively done in SourceFile and reading bytes for classfiles
- * was done in symtab.classfile.AbstractFileReader
+ * <p>
+ *   This class and its children serve to unify handling of files and
+ *   directories. These files and directories may or may not have some
+ *   real counter part within the file system. For example, some file
+ *   handles reference files within a zip archive or virtual ones
+ *   that exist only in memory.
+ * </p>
+ * <p>
+ *   Every abstract file has a path (i.e. a full name) and a name
+ *   (i.e. a short name) and may be backed by some real File. There are
+ *   two different kinds of abstract files: regular files and
+ *   directories. Regular files may be read and have a last modification
+ *   time. Directories may list their content and look for subfiles with
+ *   a specified name or path and of a specified kind.
+ * </p>
+ * <p>
+ *   bq: The interface allows to access the content as bytes and as chars.
+ *   In fact, only the ClassFileParser should access bytes, because
+ *   only there we know that the charset of the file is UTF-8. For
+ *   all other cases, the <code>global.settings.encoding.value</code> must
+ *   be respected.
+ * </p>
+ * @todo it would be better if reading chars from sources was exclusively
+ *       done in <code>SourceFile</code> and reading bytes for classfiles
+ *       was done in <code>symtab.classfile.AbstractFileReader</code>.
  */
 abstract class AbstractFile extends Object with Iterable[AbstractFile] {
 
@@ -94,19 +99,25 @@ abstract class AbstractFile extends Object with Iterable[AbstractFile] {
   /** Returns all abstract subfiles of this abstract directory. */
   def elements: Iterator[AbstractFile]
 
-  /**
-   * Returns the abstract file in this abstract directory with the
-   * specified name. If there is no such file, returns null. The
-   * argument "directory" tells whether to look for a directory or
-   * or a regular file.
+  /** Returns the abstract file in this abstract directory with the specified
+   *  name. If there is no such file, returns null. The argument
+   *  <code>directory</code> tells whether to look for a directory or
+   *  a regular file.
+   *
+   *  @param name      ...
+   *  @param directory ...
+   *  @return          ...
    */
   def lookupName(name: String, directory: Boolean): AbstractFile
 
-  /**
-   * Returns the abstract file in this abstract directory with the
-   * specified path relative to it, If there is no such file,
-   * returns null. The argument "directory" tells whether to look
-   * for a directory or a regular file.
+  /** Returns the abstract file in this abstract directory with the specified
+   *  path relative to it, If there is no such file, returns null. The argument
+   *  <code>directory</code> tells whether to look for a directory or a regular
+   *  file.
+   *
+   *  @param path      ...
+   *  @param directory ...
+   *  @return          ...
    */
   def lookupPath(path: String, directory: Boolean): AbstractFile = {
     val length = path.length()
diff --git a/src/library/scala/mobile/Code.scala b/src/library/scala/mobile/Code.scala
index 35ebd68047..e185db0f40 100644
--- a/src/library/scala/mobile/Code.scala
+++ b/src/library/scala/mobile/Code.scala
@@ -26,7 +26,7 @@ import java.lang.reflect.{Constructor, Method, Modifier}
  *    obj[Array[Int], Unit]("sort")(ar);
  *    obj[Array[Int], Unit]("println")(ar);</pre>
  *
- *  @see <a href="Location-class.html">Location</a>
+ *  @see <a href="Location.html">Location</a>
  *
  *  @author  Stephane Micheloud
  *  @version 1.0, 04/05/2004
diff --git a/src/library/scala/mobile/Location.scala b/src/library/scala/mobile/Location.scala
index 86d4b6bd37..2c6aae6cae 100644
--- a/src/library/scala/mobile/Location.scala
+++ b/src/library/scala/mobile/Location.scala
@@ -28,7 +28,7 @@ import scala.collection.mutable._
  *    <b>val</b> url = <b>new</b> URL("http://scala.epfl.ch/classes/examples.jar");
  *    <b>val</b> obj = <b>new</b> Location(url) create "examples.sort";</pre>
  *
- *  @see <a href="Code-class.html">Code</a>
+ *  @see <a href="Code.html">Code</a>
  *
  *  @author  Stephane Micheloud
  *  @version 1.0, 04/05/2004