improved handling of scaladoc comments

4 files changed, 202 insertions, 151 deletions

diff --git a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
index b18a8e5c1b..8fdbf1e3ef 100644
--- a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
+++ b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
@@ -399,15 +399,14 @@ abstract class DocGenerator extends Models {
             </tr>
             <tr>
             { {
-              if (p.decls.isEmpty) NodeSeq.Empty // scope empty
+              val decls = p.decls.toList filter(d =>
+                d.isMethod && !d.isConstructor)
+              if (decls.isEmpty) NodeSeq.Empty // scope empty
               else {
                 def aref1(sym: Symbol): NodeSeq = {
-                  val ns = sym.nameString
                   val isJava = sym hasFlag Flags.JAVA
                   if (isJava || sym.sourceFile == null) {
-                    val name =
-                      if (isJava && ns.equals("this")) sym.owner.nameString
-                      else ns
+                    val name = sym.nameString
                     val args =
                       if (isJava) "()" // todo: arguments
                       else ""
@@ -418,7 +417,7 @@ abstract class DocGenerator extends Models {
                   else
                     aref(urlFor(sym), contentFrame, sym.nameString)
                 }
-                val members = p.decls.toList.sort(
+                val members = decls.sort(
                   (x, y) => (x.nameString compareTo y.nameString) < 0)
                 <td colspan="2" class="signature">
                   {aref1(members.head)}
@@ -1113,7 +1112,7 @@ abstract class DocGenerator extends Models {
   private val pat1 = Pattern.compile(
     "[ \t]*@(author|deprecated|return|see|since|todo|version)[ \t]*(.*)")
   private val pat2 = Pattern.compile(
-    "[ \t]*@(exception|param|throws)[ \t]+(\\p{Alnum}*)[ \t]*(.*)")
+    "[ \t]*@(exception|param|throws)[ \t]+(\\p{Graph}*)[ \t]*(.*)")
 
   private def comment(comment: String, isShort: Boolean): NodeSeq = {
     var ret: List[Node] = Nil
@@ -1146,6 +1145,13 @@ abstract class DocGenerator extends Models {
           buf.append(s + LINE_SEPARATOR)
       }
     }
+    val exceptions = new TreeMap[String, Pair[Symbol, String]] +
+      "Predef.IndexOutOfBoundsException" ->
+        Pair(definitions.PredefModule, "IndexOutOfBoundsException") +
+      "Predef.NoSuchElementException" ->
+        Pair(definitions.PredefModule, "NoSuchElementException") +
+      "Predef.NullPointerException" ->
+        Pair(definitions.PredefModule, "NullPointerException")
     val body = buf.toString
     if (isShort) <span>{parse(body)}</span>;
     else <span><dl><dd>{parse(body)}</dd></dl><dl>
@@ -1156,7 +1162,19 @@ abstract class DocGenerator extends Models {
         </dt>
         <dd> {
           if (attr._2 == null) NodeSeq.Empty
-          else <code>{attr._2 + " - "}</code>
+          else if (attr._1.equals("throws"))
+            <code>{ exceptions.get(attr._2) match {
+              case Some(p) =>
+                val Pair(sym, s) = p
+                val path = "../" //todo: fix path
+                val href = path + sym.fullNameString('/')
+                  (if (sym.isModule || sym.isModuleClass) NAME_SUFFIX_OBJECT else "") +
+                  "#" + s
+                <a href={href}>{attr._2}</a>
+              case None => Text(attr._2)
+            }}{Text(" - ")}</code>
+          else
+            <code>{attr._2 + " - "}</code>
         } {(parse(attr._3.toString))}
         </dd>;
     } } </dl></span>;
diff --git a/src/compiler/scala/tools/nsc/doc/script.js b/src/compiler/scala/tools/nsc/doc/script.js
index 33278f2338..58cf9689de 100644
--- a/src/compiler/scala/tools/nsc/doc/script.js
+++ b/src/compiler/scala/tools/nsc/doc/script.js
@@ -21,100 +21,114 @@ var table = new Array()
 
 function init() {
   // initialize Java classes
-  table['java_io_BufferedReader']                = java_api_root;
-  table['java_io_BufferedWriter']                = java_api_root;
-  table['java_io_DataInputStream']               = java_api_root;
-  table['java_io_DataOutputStream']              = java_api_root;
-  table['java_io_File']                          = java_api_root;
-  table['java_io_FileDescriptor']                = java_api_root;
-  table['java_io_FileReader']                    = java_api_root;
-  table['java_io_FileWriter']                    = java_api_root;
-  table['java_io_IOException']                   = java_api_root;
-  table['java_io_InputStream']                   = java_api_root;
-  table['java_io_OutputStream']                  = java_api_root;
-  table['java_io_PrintStream']                   = java_api_root;
-  table['java_io_PrintWriter']                   = java_api_root;
-  table['java_io_Reader']                        = java_api_root;
-  table['java_io_StringReader']                  = java_api_root;
-  table['java_io_StringWriter']                  = java_api_root;
-  table['java_io_Writer']                        = java_api_root;
-  table['java_lang_Boolean']                     = java_api_root;
-  table['java_lang_Byte']                        = java_api_root;
-  table['java_lang_Character']                   = java_api_root;
-  table['java_lang_Class']                       = java_api_root;
-  table['java_lang_Clonable']                    = java_api_root; //interface
-  table['java_lang_Comparable']                  = java_api_root; //interface
-  table['java_lang_Exception']                   = java_api_root;
-  table['java_lang_Float']                       = java_api_root;
-  table['java_lang_Long']                        = java_api_root;
-  table['java_lang_Math']                        = java_api_root;
-  table['java_lang_Object']                      = java_api_root;
-  table['java_lang_Runnable']                    = java_api_root; //interface
-  table['java_lang_Runtime']                     = java_api_root;
-  table['java_lang_RuntimePermission']           = java_api_root;
-  table['java_lang_Short']                       = java_api_root;
-  table['java_lang_StrictMath']                  = java_api_root;
-  table['java_lang_String']                      = java_api_root;
-  table['java_lang_System']                      = java_api_root;
-  table['java_lang_Thread']                      = java_api_root;
-  table['java_lang_ThreadGroup']                 = java_api_root;
-  table['java_lang_ThreadLocal']                 = java_api_root;
-  table['java_lang_Throwable']                   = java_api_root;
-  table['java_lang_Void']                        = java_api_root;
-  table['java_math_BigDecimal']                  = java_api_root;
-  table['java_math_BigInteger']                  = java_api_root;
-  table['java_math_MathContext']                 = java_api_root;
-  table['java_net_InetAddress']                  = java_api_root;
-  table['java_net_ServerSocket']                 = java_api_root;
-  table['java_net_Socket']                       = java_api_root;
-  table['java_net_SocketPermission']             = java_api_root;
-  table['java_net_URI']                          = java_api_root;
-  table['java_net_URL']                          = java_api_root;
-  table['java_nio_Buffer']                       = java_api_root;
-  table['java_nio_ByteBuffer']                   = java_api_root;
-  table['java_nio_BufferOverflowException']      = java_api_root;
-  table['java_nio_ByteOrder']                    = java_api_root;
-  table['java_nio_CharBuffer']                   = java_api_root;
-  table['java_nio_DoubleBuffer']                 = java_api_root;
-  table['java_nio_FloatBuffer']                  = java_api_root;
-  table['java_nio_IntBuffer']                    = java_api_root;
-  table['java_nio_LongBuffer']                   = java_api_root;
-  table['java_nio_MappedByteBuffer']             = java_api_root;
-  table['java_nio_ShortBuffer']                  = java_api_root;
-  table['java_nio_channels_Channels']            = java_api_root;
-  table['java_nio_channels_DatagramChannel']     = java_api_root;
-  table['java_nio_channels_FileChannel']         = java_api_root;
-  table['java_nio_channels_FileLock']            = java_api_root;
-  table['java_nio_channels_Pipe']                = java_api_root;
-  table['java_nio_channels_ReadableByteChannel'] = java_api_root;
-  table['java_nio_channels_Selector']            = java_api_root;
-  table['java_nio_channels_ServerSocketChannel'] = java_api_root;
-  table['java_nio_channels_SocketChannel']       = java_api_root;
-  table['java_nio_charset_CharsetDecoder']       = java_api_root;
-  table['java_rmi_AccessException']              = java_api_root;
-  table['java_rmi_MarshalledObject']             = java_api_root;
-  table['java_rmi_Naming']                       = java_api_root;
-  table['java_rmi_RMISecurityManager']           = java_api_root;
-  table['java_rmi_Remote']                       = java_api_root; //interface
-  table['java_sql_Array']                        = java_api_root; //interface
-  table['java_sql_Blob']                         = java_api_root; //interface
-  table['java_sql_CallableStatement']            = java_api_root; //interface
-  table['java_sql_Connection']                   = java_api_root; //interface
-  table['java_sql_Date']                         = java_api_root;
-  table['java_sql_DriverManager']                = java_api_root;
-  table['java_sql_ResultSet']                    = java_api_root; //interface
-  table['java_sql_ResultSetMetaData']            = java_api_root; //interface
-  table['java_sql_SQLPermission']                = java_api_root;
-  table['java_sql_Time']                         = java_api_root;
-  table['java_sql_Timestamp']                    = java_api_root;
-  table['java_sql_Types']                        = java_api_root;
-  table['java_util_LinkedHashMap']               = java_api_root;
-  table['java_util_LinkedHashSet']               = java_api_root;
-  table['java_util_Map']                         = java_api_root;
-  table['java_util_Properties']                  = java_api_root;
-  table['java_util_Random']                      = java_api_root;
-  table['java_util_Set']                         = java_api_root;
-  table['java_util_WeakHashMap']                 = java_api_root;
+  table['java_io_BufferedReader']                   = java_api_root;
+  table['java_io_BufferedWriter']                   = java_api_root;
+  table['java_io_DataInputStream']                  = java_api_root;
+  table['java_io_DataOutputStream']                 = java_api_root;
+  table['java_io_File']                             = java_api_root;
+  table['java_io_FileDescriptor']                   = java_api_root;
+  table['java_io_FileReader']                       = java_api_root;
+  table['java_io_FileWriter']                       = java_api_root;
+  table['java_io_IOException']                      = java_api_root;
+  table['java_io_InputStream']                      = java_api_root;
+  table['java_io_OutputStream']                     = java_api_root;
+  table['java_io_PrintStream']                      = java_api_root;
+  table['java_io_PrintWriter']                      = java_api_root;
+  table['java_io_Reader']                           = java_api_root;
+  table['java_io_StringReader']                     = java_api_root;
+  table['java_io_StringWriter']                     = java_api_root;
+  table['java_io_Writer']                           = java_api_root;
+  table['java_lang_ArithmeticException']            = java_api_root;
+  table['java_lang_ArrayIndexOutOfBoundsException'] = java_api_root;
+  table['java_lang_Boolean']                        = java_api_root;
+  table['java_lang_Byte']                           = java_api_root;
+  table['java_lang_Character']                      = java_api_root;
+  table['java_lang_Class']                          = java_api_root;
+  table['java_lang_ClassCastException']             = java_api_root;
+  table['java_lang_Clonable']                       = java_api_root; //interface
+  table['java_lang_CloneNotSupportedException']     = java_api_root;
+  table['java_lang_Comparable']                     = java_api_root; //interface
+  table['java_lang_Exception']                      = java_api_root;
+  table['java_lang_Float']                          = java_api_root;
+  table['java_lang_IllegalAccessException']         = java_api_root;
+  table['java_lang_IllegalArgumentException']       = java_api_root;
+  table['java_lang_IndexOutOfBoundsException']      = java_api_root;
+  table['java_lang_InterruptedException']           = java_api_root;
+  table['java_lang_Long']                           = java_api_root;
+  table['java_lang_Math']                           = java_api_root;
+  table['java_lang_NullPointerException']           = java_api_root;
+  table['java_lang_NumberFormatException']          = java_api_root;
+  table['java_lang_Object']                         = java_api_root;
+  table['java_lang_Runnable']                       = java_api_root; //interface
+  table['java_lang_Runtime']                        = java_api_root;
+  table['java_lang_RuntimeException']               = java_api_root;
+  table['java_lang_RuntimePermission']              = java_api_root;
+  table['java_lang_Short']                          = java_api_root;
+  table['java_lang_StrictMath']                     = java_api_root;
+  table['java_lang_String']                         = java_api_root;
+  table['java_lang_System']                         = java_api_root;
+  table['java_lang_Thread']                         = java_api_root;
+  table['java_lang_ThreadGroup']                    = java_api_root;
+  table['java_lang_ThreadLocal']                    = java_api_root;
+  table['java_lang_Throwable']                      = java_api_root;
+  table['java_lang_Void']                           = java_api_root;
+  table['java_math_BigDecimal']                     = java_api_root;
+  table['java_math_BigInteger']                     = java_api_root;
+  table['java_math_MathContext']                    = java_api_root;
+  table['java_net_InetAddress']                     = java_api_root;
+  table['java_net_ServerSocket']                    = java_api_root;
+  table['java_net_Socket']                          = java_api_root;
+  table['java_net_SocketPermission']                = java_api_root;
+  table['java_net_URI']                             = java_api_root;
+  table['java_net_URL']                             = java_api_root;
+  table['java_net_URLClassLoader']                  = java_api_root;
+  table['java_net_URLConnection']                   = java_api_root;
+  table['java_net_URLDecoder']                      = java_api_root;
+  table['java_nio_Buffer']                          = java_api_root;
+  table['java_nio_ByteBuffer']                      = java_api_root;
+  table['java_nio_BufferOverflowException']         = java_api_root;
+  table['java_nio_ByteOrder']                       = java_api_root;
+  table['java_nio_CharBuffer']                      = java_api_root;
+  table['java_nio_DoubleBuffer']                    = java_api_root;
+  table['java_nio_FloatBuffer']                     = java_api_root;
+  table['java_nio_IntBuffer']                       = java_api_root;
+  table['java_nio_LongBuffer']                      = java_api_root;
+  table['java_nio_MappedByteBuffer']                = java_api_root;
+  table['java_nio_ShortBuffer']                     = java_api_root;
+  table['java_nio_channels_Channels']               = java_api_root;
+  table['java_nio_channels_DatagramChannel']        = java_api_root;
+  table['java_nio_channels_FileChannel']            = java_api_root;
+  table['java_nio_channels_FileLock']               = java_api_root;
+  table['java_nio_channels_Pipe']                   = java_api_root;
+  table['java_nio_channels_ReadableByteChannel']    = java_api_root;
+  table['java_nio_channels_Selector']               = java_api_root;
+  table['java_nio_channels_ServerSocketChannel']    = java_api_root;
+  table['java_nio_channels_SocketChannel']          = java_api_root;
+  table['java_nio_charset_CharsetDecoder']          = java_api_root;
+  table['java_rmi_AccessException']                 = java_api_root;
+  table['java_rmi_MarshalledObject']                = java_api_root;
+  table['java_rmi_Naming']                          = java_api_root;
+  table['java_rmi_RMISecurityManager']              = java_api_root;
+  table['java_rmi_Remote']                          = java_api_root; //interface
+  table['java_sql_Array']                           = java_api_root; //interface
+  table['java_sql_Blob']                            = java_api_root; //interface
+  table['java_sql_CallableStatement']               = java_api_root; //interface
+  table['java_sql_Connection']                      = java_api_root; //interface
+  table['java_sql_Date']                            = java_api_root;
+  table['java_sql_DriverManager']                   = java_api_root;
+  table['java_sql_ResultSet']                       = java_api_root; //interface
+  table['java_sql_ResultSetMetaData']               = java_api_root; //interface
+  table['java_sql_SQLPermission']                   = java_api_root;
+  table['java_sql_Time']                            = java_api_root;
+  table['java_sql_Timestamp']                       = java_api_root;
+  table['java_sql_Types']                           = java_api_root;
+  table['java_util_LinkedHashMap']                  = java_api_root;
+  table['java_util_LinkedHashSet']                  = java_api_root;
+  table['java_util_Map']                            = java_api_root;
+  table['java_util_Properties']                     = java_api_root;
+  table['java_util_Random']                         = java_api_root;
+  table['java_util_Set']                            = java_api_root;
+  table['java_util_WeakHashMap']                    = java_api_root;
 
   // initialize Scala primitive classes
   table['scala_Any']                             = scala_api_root;
@@ -132,9 +146,15 @@ function init() {
   table['scala_Null']                            = scala_api_root;
   table['scala_Short']                           = scala_api_root;
   table['scala_Unit']                            = scala_api_root;
+  table['scala_runtime_BoxedBoolean']            = scala_api_root;
+  table['scala_runtime_BoxedByte']               = scala_api_root;
+  table['scala_runtime_BoxedChar']               = scala_api_root;
+  table['scala_runtime_BoxedDouble']             = scala_api_root;
   table['scala_runtime_BoxedInt']                = scala_api_root;
-  table['scala_runtime_BoxeFloat']               = scala_api_root;
+  table['scala_runtime_BoxedFloat']              = scala_api_root;
+  table['scala_runtime_BoxedLong']               = scala_api_root;
   table['scala_runtime_BoxedNumber']             = scala_api_root;
+  table['scala_runtime_BoxedShort']              = scala_api_root;
 
   // initialize Ant classes
   table['org_apache_tools_ant_AntClassLoader']            = ant_api_root;
diff --git a/src/library/scala/List.scala b/src/library/scala/List.scala
index eb53f5173c..fcf6c1d680 100644
--- a/src/library/scala/List.scala
+++ b/src/library/scala/List.scala
@@ -379,28 +379,34 @@ object List {
 sealed abstract class List[+a] extends Seq[a] {
 
   /** Returns true if the list does not contain any elements.
-   *  @return true, iff the list is empty.
+   *  @return <code>true</code>, iff the list is empty.
    */
   override def isEmpty: Boolean
 
   /** Returns this first element of the list.
+   *
    *  @return the first element of this list.
-   *  @throws <code>Predef.NoSuchElementException</code> if the list is empty.
+   *  @throws Predef.NoSuchElementException if the list is empty.
    */
   def head: a
 
   /** Returns this list without its first element.
+   *
    *  @return this list without its first element.
-   *  @throws <code>Predef.NoSuchElementException</code> if the list is empty.
+   *  @throws Predef.NoSuchElementException if the list is empty.
    */
   def tail: List[a]
 
-  /** Add an element <code>x</code> at the beginning of this list.
-   *  <p/>
-   *  Ex:<br/>
+  /** <p>
+   *    Add an element <code>x</code> at the beginning of this list.
+   *  </p>
+   *  <p>
+   *    Example:
+   *  </p>
    *  <code>1 :: [2, 3] = [2, 3].::(1) = [1, 2, 3]</code>.
+   *
    *  @param x the element to append.
-   *  @return the list with <code>x</code> appended at the beginning.
+   *  @return  the list with <code>x</code> appended at the beginning.
    */
   def ::[b >: a] (x: b): List[b] =
     new scala.::(x, this)
@@ -493,7 +499,7 @@ sealed abstract class List[+a] extends Seq[a] {
   /** Returns the list without its last element.
    *
    *  @return the list without its last element.
-   *  @throws <code>Predef.UnsupportedOperationException</code>
+   *  @throws Predef.UnsupportedOperationException
    *  if the list is empty.
    */
   def init: List[a] =
@@ -513,7 +519,7 @@ sealed abstract class List[+a] extends Seq[a] {
   /** Returns the last element of this list.
    *
    *  @return the last element of the list.
-   *  @throws <code>Predef.UnsupportedOperationException</code>
+   *  @throws Predef.UnsupportedOperationException
    *  if the list is empty.
    */
   def last: a =
@@ -596,8 +602,8 @@ sealed abstract class List[+a] extends Seq[a] {
    *  the predicate <code>p</code>.
    *
    *  @param p the test predicate.
-   *  @return the longest prefix of this list whose elements satisfy
-   *  the predicate <code>p</code>.
+   *  @return  the longest prefix of this list whose elements satisfy
+   *           the predicate <code>p</code>.
    */
   def takeWhile(p: a => Boolean): List[a] = {
     val b = new ListBuffer[a]
@@ -613,8 +619,8 @@ sealed abstract class List[+a] extends Seq[a] {
    *  does not satisfy the predicate <code>p</code>.
    *
    *  @param p the test predicate.
-   *  @return the longest suffix of the list whose first element
-   *          does not satisfy the predicate <code>p</code>.
+   *  @return  the longest suffix of the list whose first element
+   *           does not satisfy the predicate <code>p</code>.
    */
   def dropWhile(p: a => Boolean): List[a] =
     if (isEmpty || !p(head)) this
@@ -624,8 +630,8 @@ sealed abstract class List[+a] extends Seq[a] {
    *  the given predicate, and the rest of the list.
    *
    *  @param p the test predicate
-   *  @return a pair consisting of the longest prefix of the list whose
-   *  elements all satisfy <code>p</code>, and the rest of the list.
+   *  @return  a pair consisting of the longest prefix of the list whose
+   *           elements all satisfy <code>p</code>, and the rest of the list.
    */
   def span(p: a => Boolean): Pair[List[a], List[a]] = {
     val b = new ListBuffer[a]
@@ -645,8 +651,8 @@ sealed abstract class List[+a] extends Seq[a] {
    *  (head of the list) is at position 0.
    *
    *  @param n index of the element to return
-   *  @return the element at position <code>n</code> in this list.
-   *  @throws <code>Predef.NoSuchElementException</code> if the list is too short.
+   *  @return  the element at position <code>n</code> in this list.
+   *  @throws Predef.NoSuchElementException if the list is too short.
    */
   def apply(n: Int): a = drop(n).head
 
@@ -860,8 +866,8 @@ sealed abstract class List[+a] extends Seq[a] {
    *  iterable object.
    *
    *  @param elem element whose membership has to be tested.
-   *  @return True iff there is an element of this list which is
-   *  equal (w.r.t. <code>==</code>) to <code>elem</code>.
+   *  @return     <code>true</code> iff there is an element of this list
+   *              which is equal (w.r.t. <code>==</code>) to <code>elem</code>.
    */
   def contains(elem: Any): boolean = exists (.==(elem))
 
@@ -942,9 +948,12 @@ sealed abstract class List[+a] extends Seq[a] {
     b.toList
   }
 
-  /** Reverses the elements of this list.
-   *  <p/>
-   *  Ex: <br/>
+  /** <p>
+   *    Reverses the elements of this list.
+   *  </p>
+   *  <p>
+   *    Example:
+   *  </p>
    *  <code>[1, 2, 3] reverse = [3, 2, 1]</code>.
    *
    *  @return the elements of this list in reverse order.
@@ -956,9 +965,9 @@ sealed abstract class List[+a] extends Seq[a] {
    *  <code>that</code> by associating each element of the former with
    *  the element at the same position in the latter.
    *
-   *  @param <code>that</code> must have the same length as the self list.
-   *  @return <code>[(a0,b0), ..., (an,bn)]</code> when
-   *  <code>[a0, ..., an] zip [b0, ..., bn]</code> is invoked.
+   *  @param that <code>that</code> must have the same length as the self list.
+   *  @return     <code>[(a0,b0), ..., (an,bn)]</code> when
+   *              <code>[a0, ..., an] zip [b0, ..., bn]</code> is invoked.
    */
   def zip[b](that: List[b]): List[Pair[a,b]] = {
     val b = new ListBuffer[Pair[a, b]]
@@ -975,10 +984,9 @@ sealed abstract class List[+a] extends Seq[a] {
    /** Return an list that pairs each element of this list
     *  with its index, counting from 0.
     *
-    *  @param   <code>start</code> the index of the first element
-    *
-    *  @return  an iterator yielding <code>(a0,0), (a0,1)...</code>
-    *           where <code>ai</code> are the elements from this iterator.
+    *  @param start the index of the first element
+    *  @return      an iterator yielding <code>(a0,0), (a0,1)...</code>
+    *               where <code>ai</code> are the elements from this iterator.
     */
   def zipWithIndex = {
     val b = new ListBuffer[Pair[a,int]]
@@ -998,14 +1006,17 @@ sealed abstract class List[+a] extends Seq[a] {
    *  <code>that</code> by associating each element of the former with
    *  the element at the same position in the latter.
    *
-   *  @param <code>that</code> may have a different length as the self list.
-   *  @param <code>thisElem</code> is used to fill up the resulting list if
-   *  the self list is shorter than <code>that</code>
-   *  @param <code>thatElem</code> is used to fill up the resulting list if
-   *  <code>that</code> is shorter than the self list
-   *  @return <code>[(a0,b0), ..., (an,bn), (elem,bn+1), ..., (elem,bm)]</code>
-   *  when <code>[a0, ..., an] zip [b0, ..., bm]</code> is invoked where
-   *  <code>m &gt; n</code>.
+   *  @param that     list <code>that</code> may have a different length
+   *                  as the self list.
+   *  @param thisElem element <code>thisElem</code> is used to fill up the
+   *                  resulting list if the self list is shorter than
+   *                  <code>that</code>
+   *  @param thatElem element <code>thatElem</code> is used to fill up the
+   *                  resulting list if <code>that</code> is shorter than
+   *                  the self list
+   *  @return         <code>[(a0,b0), ..., (an,bn), (elem,bn+1), ..., (elem,bm)]</code>
+   *                  when <code>[a0, ..., an] zip [b0, ..., bm]</code> is
+   *                  invoked where <code>m &gt; n</code>.
    */
   def zipAll[b, c >: a, d >: b](that: List[b], thisElem: c, thatElem: d): List[Pair[c,d]] = {
     val b = new ListBuffer[Pair[c, d]]
@@ -1031,8 +1042,8 @@ sealed abstract class List[+a] extends Seq[a] {
    *  <code>that</code>.
    *
    *  @param that the list of elements to add to the list.
-   *  @return a list without doubles containing the elements of this
-   *  list and those of the given list <code>that</code>.
+   *  @return     a list without doubles containing the elements of this
+   *              list and those of the given list <code>that</code>.
    */
   def union[b >: a](that: List[b]): List[b] = {
     val b = new ListBuffer[b]
diff --git a/src/library/scala/xml/Node.scala b/src/library/scala/xml/Node.scala
index c372ab39ee..141a9f9f1b 100644
--- a/src/library/scala/xml/Node.scala
+++ b/src/library/scala/xml/Node.scala
@@ -44,7 +44,8 @@ abstract class Node extends NodeSeq {
   /** label of this node. I.e. "foo" for &lt;foo/&gt;) */
   def label: String
 
-  /** used internally. Atom/Molecule = -1 PI = -2 Comment = -3 EntityRef = -5  */
+  /** used internally. Atom/Molecule = -1 PI = -2 Comment = -3 EntityRef = -5
+   */
   def typeTag$: Int = 0
 
   /**
@@ -54,7 +55,7 @@ abstract class Node extends NodeSeq {
   def scope: NamespaceBinding = TopScope
 
   /**
-   *  convenience, same as getNamespace(this.prefix)
+   *  convenience, same as <code>getNamespace(this.prefix)</code>
    */
   def namespace = getNamespace(this.prefix)
 
@@ -62,14 +63,15 @@ abstract class Node extends NodeSeq {
    * Convenience method, same as <code>scope.getURI(pre)</code> but additionally
    * checks if scope is <code>null</code>.
    *
-   * @param   pre the prefix whose namespace name we would like to obtain
-   * @return  the namespace if scope != null and prefix was found, else null
+   * @param pre the prefix whose namespace name we would like to obtain
+   * @return    the namespace if <code>scope != null</code> and prefix was
+   *            found, else <code>null</code>
    */
   def getNamespace(pre: String) = if (scope == null) null else scope.getURI(pre)
 
   /**
    * Convenience method, looks up an unprefixed attribute in attributes of this node.
-   * Same as attributes.getValue(key);
+   * Same as <code>attributes.getValue(key)</code>
    *
    * @param  key of queried attribute.
    * @return value of <code>UnprefixedAttribute</code> with given key
@@ -79,7 +81,7 @@ abstract class Node extends NodeSeq {
 
   /**
    * Convenience method, looks up a prefixed attribute in attributes of this node.
-   * Same as attributes.getValue(uri, this, key);
+   * Same as <code>attributes.getValue(uri, this, key)</code>
    *
    * @param  uri namespace of queried attribute (may not be null).
    * @param  key of queried attribute.
@@ -121,7 +123,7 @@ abstract class Node extends NodeSeq {
    * label, attributes and children.
    *
    * @param x ...
-   * @return  ...
+   * @return  <code>true</code> if ..
    */
   override def equals(x: Any): Boolean = x match {
     case g:Group => false
@@ -144,7 +146,7 @@ abstract class Node extends NodeSeq {
   /**
    *  returns a sequence consisting of only this node
    */
-  def theSeq:Seq[Node] = this :: Nil
+  def theSeq: Seq[Node] = this :: Nil
 
   /**
    * String representation of this node
@@ -158,7 +160,7 @@ abstract class Node extends NodeSeq {
   /**
    * Same as <code>toString(false)</code>.
    *
-   * @see "toString(Boolean)"
+   * @see <code><a href="#toString">toString(Boolean)</a></code>
    */
   override def toString(): String = toString(false)