scaladoc fixes and improvements

Changes to scaladoc include:

- fixed transformation of Code(text) into HTML tag <code>
- added tool tips for deprecated entities (classes, methods)
  using the 'title' attribute
- added syntax highlighting of Scala source code in generated
  <pre> blocks (CSS colors are defined in lib/template.css)

Here are several examples of highlighted Scala code:

scala.App
scala.Application
scala.Enumeration
scala.Function1
scala.Function2
scala.native
scala.Option
scala.Proxy
scala.specialized
scala.throws
scala.unchecked

scala.actors.Actor
scala.annotation.deprecatedName
scala.annotation.elidable
scala.annotation.switch

scala.collection.DefaultMap
scala.collection.JavaConversions
scala.collection.JavaConverters
scala.collection.LinearSeqLike
scala.collection.MapLike
scala.collection.SetLike
scala.collection.TraversableLike
scala.collection.immutable.NumericRange
scala.collection.immutable.Range
scala.collection.immutable.Stream
scala.collection.mutable.BufferLike

scala.concurrent.pilib
scala.io.Position
scala.reflect.BeanProperty
scala.reflect.Manifest
scala.testing.Benchmark

scala.util.DynamicVariable
scala.util.control.Breaks
scala.util.control.ControlThrowable
scala.util.control.Exception
scala.util.control.TailCalls
scala.util.logging.Logged
scala.util.parsing.combinator.testing.Tester
scala.util.parsing.json.JSON
scala.util.regexp.WordExp

scala.xml.factory.LoggedNodeFactory
scala.xml.parsing.ConstructingParser



git-svn-id: http://lampsvn.epfl.ch/svn-repos/scala/scala/trunk@25294 5e8d7ff9-d8ef-0310-90f0-a4852d11357a

Author: michelou

src/compiler/scala/reflect/api/Trees.scala

@@ -356,20 +356,16 @@ trait Trees /*extends reflect.generic.Trees*/ { self: Universe =>
   case class If(cond: Tree, thenp: Tree, elsep: Tree)
        extends TermTree
 
-  /** <p>
-   *    Pattern matching expression  (before explicitouter)
-   *    Switch statements            (after explicitouter)
-   *  </p>
-   *  <p>
-   *    After explicitouter, cases will satisfy the following constraints:
-   *  </p>
-   *  <ul>
-   *    <li>all guards are EmptyTree,</li>
-   *    <li>all patterns will be either <code>Literal(Constant(x:Int))</code>
-   *      or <code>Alternative(lit|...|lit)</code></li>
-   *    <li>except for an "otherwise" branch, which has pattern
-   *      <code>Ident(nme.WILDCARD)</code></li>
-   *  </ul>
+  /** - Pattern matching expression  (before explicitouter)
+   *  - Switch statements            (after explicitouter)
+   *  
+   *  After explicitouter, cases will satisfy the following constraints:
+   *  
+   *  - all guards are `EmptyTree`,
+   *  - all patterns will be either `Literal(Constant(x:Int))`
+   *    or `Alternative(lit|...|lit)`
+   *  - except for an "otherwise" branch, which has pattern
+   *    `Ident(nme.WILDCARD)`
    */
   case class Match(selector: Tree, cases: List[CaseDef])
        extends TermTree

src/compiler/scala/reflect/internal/AnnotationInfos.scala

@@ -13,36 +13,38 @@ trait AnnotationInfos extends api.AnnotationInfos { self: SymbolTable =>
 
   /** Arguments to classfile annotations (which are written to
    *  bytecode as java annotations) are either:
-   *  <ul>
-   *   <li>constants</li>
-   *   <li>arrays of constants</li>
-   *   <li>or nested classfile annotations</li>
-   *  </ul>
+   *  
+   *  - constants
+   *  - arrays of constants
+   *  - or nested classfile annotations
    */
   abstract class ClassfileAnnotArg
 
-  /** Represents a compile-time Constant (Boolean, Byte, Short,
-   *  Char, Int, Long, Float, Double, String, java.lang.Class or
+  /** Represents a compile-time Constant (`Boolean`, `Byte`, `Short`,
+   *  `Char`, `Int`, `Long`, `Float`, `Double`, `String`, `java.lang.Class` or
    *  an instance of a Java enumeration value).
    */
   case class LiteralAnnotArg(const: Constant)
   extends ClassfileAnnotArg {
     override def toString = const.escapedStringValue
   }
-  
+
   object LiteralAnnotArg extends LiteralAnnotArgExtractor
-  
+
   /** Represents an array of classfile annotation arguments */
   case class ArrayAnnotArg(args: Array[ClassfileAnnotArg])
   extends ClassfileAnnotArg {
     override def toString = args.mkString("[", ", ", "]")
   }
-  
+
   object ArrayAnnotArg extends ArrayAnnotArgExtractor
 
-  /** A specific annotation argument that encodes an array of bytes as an array of `Long`. The type of the argument
-    * declared in the annotation must be `String`. This specialised class is used to encode scala signatures for
-    * reasons of efficiency, both in term of class-file size and in term of compiler performance. */
+  /** A specific annotation argument that encodes an array of bytes as an
+   *  array of `Long`. The type of the argument declared in the annotation
+   *  must be `String`. This specialised class is used to encode Scala
+   *  signatures for reasons of efficiency, both in term of class-file size
+   *  and in term of compiler performance.
+   */
   case class ScalaSigBytes(bytes: Array[Byte]) extends ClassfileAnnotArg {
     override def toString = (bytes map { byte => (byte & 0xff).toHexString }).mkString("[ ", " ", " ]")
     lazy val encodedBytes = ByteCodecs.encode(bytes)
@@ -61,35 +63,26 @@ trait AnnotationInfos extends api.AnnotationInfos { self: SymbolTable =>
     assert(annInfo.args.isEmpty, annInfo.args)
     override def toString = annInfo.toString
   }
-  
+
   object NestedAnnotArg extends NestedAnnotArgExtractor
 
   class AnnotationInfoBase
 
-  /** <p>
-   *    Typed information about an annotation. It can be attached to
-   *    either a symbol or an annotated type.
-   *  </p>
-   *  <p>
-   *    Annotations are written to the classfile as java annotations
-   *    if <code>atp</code> conforms to <code>ClassfileAnnotation</code>
-   *    (the classfile parser adds this interface to any Java annotation
-   *    class).
-   *  </p>
-   *  <p>
-   *    Annotations are pickled (written to scala symtab attribute
-   *    in the classfile) if <code>atp</code> inherits form
-   *    <code>StaticAnnotation</code>.
-   *  </p>
-   *  <p>
-   *    <code>args</code> stores arguments to Scala annotations,
-   *    represented as  typed trees. Note that these trees are not
-   *    transformed by any phases following the type-checker.
-   *  </p>
-   *  <p>
-   *    <code>assocs</code> stores arguments to classfile annotations
-   *    as name-value pairs.
-   *  </p>
+  /** Typed information about an annotation. It can be attached to either
+   *  a symbol or an annotated type.
+   *  
+   *  Annotations are written to the classfile as Java annotations
+   *  if `atp` conforms to `ClassfileAnnotation` (the classfile parser adds
+   *  this interface to any Java annotation class).
+   *  
+   *  Annotations are pickled (written to scala symtab attribute in the
+   *  classfile) if `atp` inherits form `StaticAnnotation`.
+   *  
+   *  `args` stores arguments to Scala annotations, represented as typed
+   *  trees. Note that these trees are not transformed by any phases
+   *  following the type-checker.
+   *  
+   *  `assocs` stores arguments to classfile annotations as name-value pairs.
    */
   case class AnnotationInfo(atp: Type, args: List[Tree],
                             assocs: List[(Name, ClassfileAnnotArg)])
@@ -136,13 +129,13 @@ trait AnnotationInfos extends api.AnnotationInfos { self: SymbolTable =>
       case Literal(Constant(x: Int)) => x
     } else None
   }
-  
+
   object AnnotationInfo extends AnnotationInfoExtractor
 
   lazy val classfileAnnotArgManifest: ClassManifest[ClassfileAnnotArg] =
     reflect.ClassManifest.classType(classOf[ClassfileAnnotArg])
 
-  /** Symbol annotations parsed in Namer (typeCompleter of
+  /** Symbol annotations parsed in `Namer` (typeCompleter of
    *  definitions) have to be lazy (#1782)
    */
   case class LazyAnnotationInfo(annot: () => AnnotationInfo)

src/compiler/scala/tools/nsc/backend/WorklistAlgorithm.scala

@@ -3,7 +3,6 @@
  * @author  Martin Odersky
  */
 
-
 package scala.tools.nsc
 package backend
 
@@ -15,14 +14,13 @@ import scala.collection.{ mutable, immutable }
  * function is applied repeatedly to the first element in the
  * worklist, as long as the stack is not empty.
  *
- * The client class should mix-in this class and initialize the
- * worklist field and define the <code>processElement</code> method.
- * Then call the <code>run</code> method providing a function that
- * initializes the worklist.
+ * The client class should mix-in this class and initialize the worklist
+ * field and define the `processElement` method. Then call the `run` method
+ * providing a function that initializes the worklist.
  *
  * @author  Martin Odersky
  * @version 1.0
- * @see     <a href="icode/Linearizers.html" target="contentFrame">scala.tools.nsc.backend.icode.Linearizers</a>
+ * @see     [[scala.tools.nsc.backend.icode.Linearizers]]
  */
 trait WorklistAlgorithm {
   type Elem
@@ -31,9 +29,9 @@ trait WorklistAlgorithm {
   val worklist: WList
 
   /**
-   * Run the iterative algorithm until the worklist
-   * remains empty. The initializer is run once before
-   * the loop starts and should initialize the worklist.
+   * Run the iterative algorithm until the worklist remains empty.
+   * The initializer is run once before the loop starts and should
+   * initialize the worklist.
    *
    * @param initWorklist ...
    */

src/compiler/scala/tools/nsc/backend/icode/analysis/TypeFlowAnalysis.scala

@@ -3,13 +3,12 @@
  * @author  Martin Odersky
  */
 
-
 package scala.tools.nsc
 package backend.icode.analysis
 
 import scala.collection.{mutable, immutable}
 
-/** A data-flow analysis on types, that works on <code>ICode</code>.
+/** A data-flow analysis on types, that works on `ICode`.
  *
  *  @author Iulian Dragos
  */
@@ -95,7 +94,7 @@ abstract class TypeFlowAnalysis {
   }
 
   val timer = new Timer
-  
+
   class MethodTFA extends DataFlowAnalysis[typeFlowLattice.type] {
     import icodes._
     import icodes.opcodes._

src/compiler/scala/tools/nsc/doc/DocFactory.scala

@@ -1,4 +1,7 @@
-/* NSC -- new Scala compiler -- Copyright 2007-2011 LAMP/EPFL */
+/* NSC -- new Scala compiler
+ * Copyright 2007-2011 LAMP/EPFL
+ * @author  David Bernard, Manohar Jonnalagedda
+ */
 
 package scala.tools.nsc
 package doc
@@ -9,18 +12,20 @@ import util.NoPosition
 import io.{ File, Directory }
 import DocParser.Parsed
 
-/** A documentation processor controls the process of generating Scala documentation, which is as follows.
+/** A documentation processor controls the process of generating Scala
+  * documentation, which is as follows.
   *
-  * * A simplified compiler instance (with only the front-end phases enabled) is created, and additional
-  *   ''sourceless'' comments are registered.
+  * * A simplified compiler instance (with only the front-end phases enabled)
+  * * is created, and additional ''sourceless'' comments are registered.
   * * Documentable files are compiled, thereby filling the compiler's symbol table.
   * * A documentation model is extracted from the post-compilation symbol table.
   * * A generator is used to transform the model into the correct final format (HTML).
   *
-  * A processor contains a single compiler instantiated from the processor's `settings`. Each call to `document`
-  * uses the same compiler instance with the same symbol table. In particular, this implies that the scaladoc site
-  * obtained from a call to `run` will contain documentation about files compiled during previous calls to the same
-  * processor's `run` method.
+  * A processor contains a single compiler instantiated from the processor's
+  * `settings`. Each call to `document` uses the same compiler instance with
+  * the same symbol table. In particular, this implies that the scaladoc site
+  * obtained from a call to `run` will contain documentation about files compiled
+  * during previous calls to the same processor's `run` method.
   *
   * @param reporter The reporter to which both documentation and compilation errors will be reported.
   * @param settings The settings to be used by the documenter and compiler for generating documentation.
@@ -41,9 +46,10 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor
     override def forScaladoc = true
   }
 
-  /** Creates a scaladoc site for all symbols defined in this call's `files`, as well as those defined in `files` of
-    * previous calls to the same processor.
-    * @param files The list of paths (relative to the compiler's source path, or absolute) of files to document. */
+  /** Creates a scaladoc site for all symbols defined in this call's `files`,
+    * as well as those defined in `files` of previous calls to the same processor.
+    * @param files The list of paths (relative to the compiler's source path,
+    *        or absolute) of files to document. */
   def makeUniverse(files: List[String]): Option[Universe] = {
     assert(settings.docformat.value == "html")
     new compiler.Run() compile files
@@ -83,9 +89,9 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor
         println("no documentable class found in compilation units")
         None
     }
-    
+
   }
-  
+
   object NoCompilerRunException extends ControlThrowable { }
 
   val documentError: PartialFunction[Throwable, Unit] = {
@@ -97,7 +103,7 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor
 
   /** Generate document(s) for all `files` containing scaladoc documenataion.
     * @param files The list of paths (relative to the compiler's source path, or absolute) of files to document. */
-  def document(files: List[String]): Unit = {
+  def document(files: List[String]) {
     def generate() = {
       import doclet._
       val docletClass    = Class.forName(settings.docgenerator.value) // default is html.Doclet
@@ -107,7 +113,7 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor
         case universer: Universer =>
           val universe = makeUniverse(files) getOrElse { throw NoCompilerRunException }
           universer setUniverse universe
-          
+
           docletInstance match {
             case indexer: Indexer => indexer setIndex model.IndexModelFactory.makeIndex(universe)
             case _                => ()
@@ -116,10 +122,11 @@ class DocFactory(val reporter: Reporter, val settings: doc.Settings) { processor
       }
       docletInstance.generate
     }
-    
+
     try generate()
     catch documentError
   }
+
   private[doc] def docdbg(msg: String) {
     if (settings.Ydocdebug.value)
       println(msg)

src/compiler/scala/tools/nsc/doc/DocParser.scala

@@ -12,8 +12,8 @@ import util._
 import interactive.RangePositions
 import DocParser.Parsed
 
-/** A very minimal global customized for extracting DocDefs.  It stops
- *  right after parsing so it can read DocDefs from source code which would
+/** A very minimal global customized for extracting `DocDefs`.  It stops
+ *  right after parsing so it can read `DocDefs` from source code which would
  *  otherwise cause the compiler to go haywire.
  */
 class DocParser(settings: nsc.Settings, reporter: Reporter)
@@ -31,8 +31,8 @@ class DocParser(settings: nsc.Settings, reporter: Reporter)
     phasesSet += syntaxAnalyzer
   }
 
-  /** Returns a list of DocParser.Parseds, which hold the DocDefs found in the
-   *  given code along with the surrounding trees.
+  /** Returns a list of `DocParser.Parseds`, which hold the DocDefs found
+   *  in the given code along with the surrounding trees.
    */
   def docDefs(code: String) = {
     def loop(enclosing: List[Tree], tree: Tree): List[Parsed] = tree match {
@@ -54,7 +54,7 @@ class DocParser(settings: nsc.Settings, reporter: Reporter)
 }
 
 /** Since the DocParser's whole reason for existing involves trashing a
- *  global, it is designed to bottle up general Global#Tree types rather
+ *  global, it is designed to bottle up general `Global#Tree` types rather
  *  than path dependent ones.  The recipient will have to deal.
  */
 object DocParser {

src/compiler/scala/tools/nsc/doc/Index.scala

@@ -1,3 +1,8 @@
+/* NSC -- new Scala compiler
+ * Copyright 2005-2011 LAMP/EPFL
+ * @author  Martin Odersky
+ */
+
 package scala.tools.nsc.doc
 
 import scala.collection._

src/compiler/scala/tools/nsc/doc/Settings.scala

@@ -12,7 +12,7 @@ import java.lang.System
 /** An extended version of compiler settings, with additional Scaladoc-specific options.
   * @param error A function that prints a string to the appropriate error stream. */
 class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) {
-  
+
   /** A setting that defines in which format the documentation is output. ''Note:'' this setting is currently always
     * `html`. */
   val docformat = ChoiceSetting (
@@ -40,13 +40,14 @@ class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) {
     "An optional version number, to be appended to the title",
     ""
   )
-  
+
   val docUncompilable = StringSetting (
     "-doc-no-compile",
     "path",
     "A directory containing sources which should be parsed, no more (e.g. AnyRef.scala)",
     ""
   )
+
   lazy val uncompilableFiles = docUncompilable.value match {
     case ""     => Nil
     case path   => io.Directory(path).deepFiles filter (_ hasExtension "scala") toList
@@ -57,7 +58,7 @@ class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) {
   val docsourceurl = StringSetting (
     "-doc-source-url",
     "url",
-    "A URL pattern used to build links to template sources; use variables, for example: €{TPL_NAME} ('Seq'), €{TPL_OWNER} ('scala.collection'), €{FILE_PATH} ('scala/collection/Seq')",
+    "A URL pattern used to build links to template sources; use variables, for example: ?{TPL_NAME} ('Seq'), ?{TPL_OWNER} ('scala.collection'), ?{FILE_PATH} ('scala/collection/Seq')",
     ""
   )
 

src/compiler/scala/tools/nsc/doc/Universe.scala

@@ -1,3 +1,8 @@
+/* NSC -- new Scala compiler
+ * Copyright 2005-2011 LAMP/EPFL
+ * @author  Martin Odersky
+ */
+
 package scala.tools.nsc.doc
 
 /**