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

4 files changed, 47 insertions, 14 deletions

diff --git a/src/compiler/scala/tools/nsc/doc/html/page/Index.scala b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala
index 7203230084..346780147e 100644
--- a/src/compiler/scala/tools/nsc/doc/html/page/Index.scala
+++ b/src/compiler/scala/tools/nsc/doc/html/page/Index.scala
@@ -109,6 +109,7 @@ class Index(universe: doc.Universe, index: doc.Index) extends HtmlPage {
     </div>
 
   def packageQualifiedName(ety: DocTemplateEntity): String =
-    if (ety.inTemplate.isPackage) ety.name else (packageQualifiedName(ety.inTemplate) + "." + ety.name)
+    if (ety.inTemplate.isPackage) ety.name
+    else (packageQualifiedName(ety.inTemplate) + "." + ety.name)
 
 }
diff --git a/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala b/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala
index 2cafe6caa3..7edd4937c4 100644
--- a/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala
+++ b/src/compiler/scala/tools/nsc/doc/html/page/IndexScript.scala
@@ -1,4 +1,10 @@
+/* NSC -- new Scala compiler
+ * Copyright 2007-2011 LAMP/EPFL
+ * @author  David Bernard, Manohar Jonnalagedda
+ */
+
 package scala.tools.nsc.doc.html.page
+
 import scala.tools.nsc.doc
 import scala.tools.nsc.doc.model.{Package, DocTemplateEntity}
 import scala.tools.nsc.doc.html.{Page, HtmlFactory}
@@ -8,7 +14,7 @@ import scala.util.parsing.json.{JSONObject, JSONArray}
 class IndexScript(universe: doc.Universe, index: doc.Index) extends Page {
   def path = List("index.js")
 
-  override def writeFor(site: HtmlFactory): Unit = {
+  override def writeFor(site: HtmlFactory) {
     val stream = createFileOutputStream(site)
     val writer = Channels.newWriter(stream.getChannel, site.encoding)
     try {
diff --git a/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala b/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala
index 3e57f260c3..a76cc231b4 100755
--- a/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala
+++ b/src/compiler/scala/tools/nsc/doc/html/page/ReferenceIndex.scala
@@ -11,7 +11,7 @@ import doc.model._
 
 class ReferenceIndex(letter: Char, index: doc.Index, universe: Universe) extends HtmlPage {
 
-  def path = List("index-"+letter+".html","index")
+  def path = List("index-"+letter+".html", "index")
 
   def title = {
     val s = universe.settings
diff --git a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala
index 61a445e2a3..ccc40013f1 100644
--- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala
+++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala
@@ -45,9 +45,9 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage {
     case _ => Nil
   })
 
-  /* for body, there is a special case for AnyRef, otherwise AnyRef appears like a package/object
-   * this problem should be fixed, this implementation is just a patch
-   */
+  /* for body, there is a special case for AnyRef, otherwise AnyRef appears
+   * like a package/object this problem should be fixed, this implementation
+   * is just a patch. */
   val body = {
     val templateName = if (tpl.isRootPackage) "root package" else tpl.name
     val displayName = tpl.companion match {
@@ -63,7 +63,8 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage {
         <p id="owner">{ templatesToHtml(tpl.inTemplate.toRoot.reverse.tail, xml.Text(".")) }</p>
     }
 
-    <body class={ if (tpl.isTrait || tpl.isClass || tpl.qualifiedName == "scala.AnyRef") "type" else "value" }>
+    <body class={ if (tpl.isTrait || tpl.isClass || tpl.qualifiedName == "scala.AnyRef") "type" else "value" }
+          onload={ "sh_highlightDocument('../lib/', '.min.js');" }>
       <div id="definition">
         {
           tpl.companion match {
@@ -339,7 +340,7 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage {
       val annotationsWithHiddenArguments = List("deprecated", "Deprecated", "migration")
 
       def showArguments(annotation: Annotation) =
-        if (annotationsWithHiddenArguments.contains(annotation.qualifiedName)) false else true
+        !(annotationsWithHiddenArguments.contains(annotation.qualifiedName))
 
       if (!mbr.annotations.isEmpty) {
         <dt>Annotations</dt>
@@ -522,7 +523,13 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage {
       <span class="kind">{ kindToString(mbr) }</span>
       <span class="symbol">
         {
-          val nameHtml = <span class={"name" + (if (mbr.deprecation.isDefined) " deprecated" else "") }>{ if (mbr.isConstructor) tpl.name else mbr.name }</span>
+          val nameHtml = {
+            val value = if (mbr.isConstructor) tpl.name else mbr.name
+            if (mbr.deprecation.isDefined)
+              <span class={"name deprecated"} title={"Deprecated: "+bodyToStr(mbr.deprecation.get)}>{ value }</span>
+            else
+              <span class={"name"}>{ value }</span>
+          }
           if (!nameLink.isEmpty)
             <a href={nameLink}>{nameHtml}</a>
           else nameHtml
@@ -616,7 +623,7 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage {
     def codeStringToXml(text: String): NodeSeq = {
       var goodLookingXml: NodeSeq = NodeSeq.Empty
       var indent = 0
-      for(c<-text) c match {
+      for (c <- text) c match {
         case '{' => indent+=1
           goodLookingXml ++= Text("{")
         case '}' => indent-=1
@@ -637,7 +644,7 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage {
     val str = tree.expression
     val length = str.length
     var myXml: NodeSeq = NodeSeq.Empty
-    for( (from, (member, to)) <- tree.refEntity.toSeq) {
+    for ((from, (member, to)) <- tree.refEntity.toSeq) {
       if (index < from) {
         myXml ++= codeStringToXml(str.substring(index,from))
         index = from
@@ -664,13 +671,13 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage {
     if (index <= length-1)
       myXml ++= codeStringToXml(str.substring(index, length ))
 
-    if(length < 36)
+    if (length < 36)
       <span class="symbol">{ myXml }</span>
     else
       <span class="defval" name={ myXml }>{ "..." }</span>
   }
 
-  def argumentsToHtml(argss: List[ValueArgument]): NodeSeq = {
+  private def argumentsToHtml(argss: List[ValueArgument]): NodeSeq = {
     def argumentsToHtml0(argss: List[ValueArgument]): NodeSeq = argss match {
       case Nil         => NodeSeq.Empty
       case arg :: Nil  => argumentToHtml(arg)
@@ -679,7 +686,7 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage {
     <span class="args">({ argumentsToHtml0(argss) })</span>
   }
 
-  def argumentToHtml(arg: ValueArgument): NodeSeq = {
+  private def argumentToHtml(arg: ValueArgument): NodeSeq = {
     <span>
       {
         arg.parameter match {
@@ -691,4 +698,23 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage {
     </span>
   }
 
+  private def bodyToStr(body: comment.Body): String =
+    body.blocks flatMap (blockToStr(_)) mkString ""
+
+  private def blockToStr(block: comment.Block): String = block match {
+    case comment.Paragraph(in) => inlineToStr(in)
+    case _ => block.toString
+  }
+
+  private def inlineToStr(inl: comment.Inline): String = inl match {
+    case comment.Chain(items) => items flatMap (inlineToStr(_)) mkString ""
+    case comment.Italic(in) => inlineToStr(in)
+    case comment.Bold(in) => inlineToStr(in)
+    case comment.Underline(in) => inlineToStr(in)
+    case comment.Monospace(in) => inlineToStr(in)
+    case comment.Text(text) => text
+    case comment.Summary(in) => inlineToStr(in)
+    case _ => inl.toString
+  }
+
 }