SI-4476 add an index of deprecated members to scaladoc

The deprecated list is only emitted if there actually are deprecated members; same for the link in the left sidebar. We just build on the existing index support, with an additional method to avoid having to go through the whole index if we won't generate the page anyway. The deprecated list page itself is completely identical to the normal index pages, except we don't strike through any entry (there are *all* deprecated already). There is just about enough space in the left sidebar for the deprecated link, see [1], and [2] for when there are no deprecated members. [1]: http://static.gourlaysama.net/img/scaladoc-deprecated.png [2]: http://static.gourlaysama.net/img/scaladoc-deprecated-empty.png
author: Antoine Gourlay <antoine@gourlay.fr> 2015-04-16 17:24:12 +0200
committer: Antoine Gourlay <antoine@gourlay.fr> 2015-04-22 16:01:51 +0200
commit: a3e93d95215b96740306d10a17a858f407ca39e5 (patch)
tree: e3653a59acef67d1c9e05ca7b0e77bff984c0426
parent: d2a174d27bce392329a9c5e4c7d2acee263cdb34 (diff)
download: scala-a3e93d95215b96740306d10a17a858f407ca39e5.tar.gz
scala-a3e93d95215b96740306d10a17a858f407ca39e5.tar.bz2
scala-a3e93d95215b96740306d10a17a858f407ca39e5.zip
8 files changed, 140 insertions, 4 deletions
diff --git a/src/scaladoc/scala/tools/nsc/doc/Index.scala b/src/scaladoc/scala/tools/nsc/doc/Index.scala
index 84545e9201..a11ca38a86 100644
--- a/src/scaladoc/scala/tools/nsc/doc/Index.scala
+++ b/src/scaladoc/scala/tools/nsc/doc/Index.scala
@@ -11,4 +11,6 @@ trait Index {
   type SymbolMap = SortedMap[String, SortedSet[model.MemberEntity]]
 
   def firstLetterIndex: Map[Char, SymbolMap]
+
+  def hasDeprecatedMembers: Boolean
 }
diff --git a/src/scaladoc/scala/tools/nsc/doc/html/HtmlFactory.scala b/src/scaladoc/scala/tools/nsc/doc/html/HtmlFactory.scala
index 61ab18d42d..8313d842e5 100644
--- a/src/scaladoc/scala/tools/nsc/doc/html/HtmlFactory.scala
+++ b/src/scaladoc/scala/tools/nsc/doc/html/HtmlFactory.scala
@@ -123,6 +123,8 @@ class HtmlFactory(val universe: doc.Universe, index: doc.Index) {
 
     new page.Index(universe, index) writeFor this
     new page.IndexScript(universe, index) writeFor this
+    if (index.hasDeprecatedMembers)
+      new page.DeprecatedIndex(universe, index) writeFor this
     try {
       writeTemplates(_ writeFor this)
       for (letter <- index.firstLetterIndex) {
diff --git a/src/scaladoc/scala/tools/nsc/doc/html/page/DeprecatedIndex.scala b/src/scaladoc/scala/tools/nsc/doc/html/page/DeprecatedIndex.scala
new file mode 100755
index 0000000000..f257153bd7
--- /dev/null
+++ b/src/scaladoc/scala/tools/nsc/doc/html/page/DeprecatedIndex.scala
@@ -0,0 +1,58 @@
+/* NSC -- new Scala compiler
+ * Copyright 2007-2013 LAMP/EPFL
+ */
+
+package scala
+package tools
+package nsc
+package doc
+package html
+package page
+
+import doc.model._
+
+class DeprecatedIndex(universe: Universe, index: doc.Index) extends HtmlPage {
+
+  def path = List("deprecated-list.html")
+
+  def title = {
+    val s = universe.settings
+    ( if (!s.doctitle.isDefault) s.doctitle.value else "" ) +
+    ( if (!s.docversion.isDefault) (" " + s.docversion.value) else "" )
+  }
+
+  def headers =
+    <xml:group>
+      <link href={ relativeLinkTo(List("ref-index.css", "lib")) }  media="screen" type="text/css" rel="stylesheet"/>
+      <script type="text/javascript" src={ relativeLinkTo{List("jquery.js", "lib")} }></script>
+    </xml:group>
+
+
+  private def entry(name: String, methods: Iterable[MemberEntity]) = {
+    val occurrences = methods.filter(_.deprecation.isDefined).map(method =>
+      templateToHtml(method.inDefinitionTemplates.head)
+    ).toList.distinct
+
+    <div class="entry">
+      <div class="name">{ name }</div>
+      <div class="occurrences">{
+        for (owner <- occurrences) yield owner ++ scala.xml.Text(" ")
+      }</div>
+    </div>
+  }
+
+  def deprecatedEntries = {
+    val available =  ('_' +: ('a' to 'z')).flatMap(index.firstLetterIndex.get)
+
+    for (group <- available;
+         value <- group if value._2.find(_.deprecation.isDefined).isDefined)
+       yield value
+  }
+
+  def body =
+    <body>{
+      for(value <- deprecatedEntries) yield
+        entry(value._1, value._2.view)
+    }</body>
+
+}
diff --git a/src/scaladoc/scala/tools/nsc/doc/html/page/Index.scala b/src/scaladoc/scala/tools/nsc/doc/html/page/Index.scala
index ce3a5eb1fc..6bfe480e33 100644
--- a/src/scaladoc/scala/tools/nsc/doc/html/page/Index.scala
+++ b/src/scaladoc/scala/tools/nsc/doc/html/page/Index.scala
@@ -61,12 +61,17 @@ class Index(universe: doc.Universe, val index: doc.Index) extends HtmlPage {
       }
     }
 
+  def deprecated: NodeSeq = if (index.hasDeprecatedMembers)
+      <a target="template" href="deprecated-list.html">deprecated</a>
+    else
+      <span>deprecated</span>
+
   def browser =
     <div id="browser" class="ui-layout-west">
       <div class="ui-west-center">
       <div id="filter">
           <div id="textfilter"></div>
-          <div id="letters">{ letters }</div>
+          <div id="letters">{ letters } &#8211; { deprecated }</div>
       </div>
       <div class="pack" id="tpl">{
         def packageElem(pack: model.Package): NodeSeq = {
diff --git a/src/scaladoc/scala/tools/nsc/doc/model/IndexModelFactory.scala b/src/scaladoc/scala/tools/nsc/doc/model/IndexModelFactory.scala
index 643a089aae..ad53dc6bfa 100755
--- a/src/scaladoc/scala/tools/nsc/doc/model/IndexModelFactory.scala
+++ b/src/scaladoc/scala/tools/nsc/doc/model/IndexModelFactory.scala
@@ -14,10 +14,12 @@ object IndexModelFactory {
 
   def makeIndex(universe: Universe): Index = new Index {
 
-    lazy val firstLetterIndex: Map[Char, SymbolMap] = {
+    lazy val (firstLetterIndex, hasDeprecatedMembers): (Map[Char, SymbolMap], Boolean) = {
 
       object result extends mutable.HashMap[Char,SymbolMap] {
 
+        var deprecated = false
+
         /* symbol name ordering */
         implicit def orderingMap = math.Ordering.String
 
@@ -32,6 +34,8 @@ object IndexModelFactory {
           val members = letter.get(d.name).getOrElse {
             SortedSet.empty[MemberEntity](Ordering.by { _.toString })
           } + d
+          if (!deprecated && members.find(_.deprecation.isDefined).isDefined)
+            deprecated = true
           this(firstLetter) = letter + (d.name -> members)
         }
       }
@@ -50,7 +54,7 @@ object IndexModelFactory {
 
       gather(universe.rootPackage)
 
-      result.toMap
+      (result.toMap, result.deprecated)
     }
   }
 }
diff --git a/test/scaladoc/resources/SI-4476.scala b/test/scaladoc/resources/SI-4476.scala
new file mode 100644
index 0000000000..eb35ef45e7
--- /dev/null
+++ b/test/scaladoc/resources/SI-4476.scala
@@ -0,0 +1,9 @@
+package foo
+
+@deprecated("","")
+class A
+
+class B {
+  @deprecated("","")
+  def bar = 1
+}
diff --git a/test/scaladoc/scalacheck/DeprecatedIndexTest.scala b/test/scaladoc/scalacheck/DeprecatedIndexTest.scala
new file mode 100644
index 0000000000..4a5a2001d4
--- /dev/null
+++ b/test/scaladoc/scalacheck/DeprecatedIndexTest.scala
@@ -0,0 +1,50 @@
+import org.scalacheck._
+import org.scalacheck.Prop._
+
+import scala.tools.nsc.doc
+import scala.tools.nsc.doc.html.page.DeprecatedIndex
+import java.net.{URLClassLoader, URLDecoder}
+
+object Test extends Properties("IndexScript") {
+
+  def getClasspath = {
+    // these things can be tricky
+    // this test previously relied on the assumption that the current thread's classloader is an url classloader and contains all the classpaths
+    // does partest actually guarantee this? to quote Leonard Nimoy: The answer, of course, is no.
+    // this test _will_ fail again some time in the future.
+    // Footnote: java.lang.ClassCastException: org.apache.tools.ant.loader.AntClassLoader5 cannot be cast to java.net.URLClassLoader
+    val loader = Thread.currentThread.getContextClassLoader.asInstanceOf[URLClassLoader]
+    val paths = loader.getURLs.map(u => URLDecoder.decode(u.getPath))
+    paths mkString java.io.File.pathSeparator
+  }
+
+  val docFactory = {
+    val settings = new doc.Settings({Console.err.println(_)})
+    settings.scaladocQuietRun = true
+    settings.nowarn.value = true
+    settings.classpath.value = getClasspath
+    val reporter = new scala.tools.nsc.reporters.ConsoleReporter(settings)
+    new doc.DocFactory(reporter, settings)
+  }
+
+  val indexModelFactory = doc.model.IndexModelFactory
+
+  def createDeprecatedScript(path: String) =
+    docFactory.makeUniverse(Left(List(path))) match {
+      case Some(universe) => {
+        val index = new DeprecatedIndex(universe, indexModelFactory.makeIndex(universe))
+        Some(index)
+      }
+      case _ =>
+        None
+    }
+
+    property("deprecated-list page lists deprecated members") = {
+      createDeprecatedScript("test/scaladoc/resources/SI-4476.scala") match {
+        case Some(p) =>
+          p.deprecatedEntries.find(_._1 == "A").isDefined &&
+          p.deprecatedEntries.find(_._1 == "bar").isDefined
+        case None => false
+      }
+    }
+}
diff --git a/test/scaladoc/scalacheck/IndexTest.scala b/test/scaladoc/scalacheck/IndexTest.scala
index abc0e5da01..7dbd2103a6 100644
--- a/test/scaladoc/scalacheck/IndexTest.scala
+++ b/test/scaladoc/scalacheck/IndexTest.scala
@@ -71,7 +71,7 @@ object Test extends Properties("Index") {
       case None => false
     }
   }
-  property("browser contants a script element") = {
+  property("browser contains a script element") = {
     createIndex("src/scaladoc/scala/tools/nsc/doc/html/page/Index.scala") match {
       case Some(index) =>
         (index.browser \ "script").size == 1
@@ -86,4 +86,10 @@ object Test extends Properties("Index") {
       case None => false
     }
   }
+  property("index should report if there are deprecated members") = {
+    createIndex("test/scaladoc/resources/SI-4476.scala") match {
+      case Some(indexPage) => indexPage.index.hasDeprecatedMembers
+      case None => false
+    }
+  }
 }
author	Antoine Gourlay <antoine@gourlay.fr>	2015-04-16 17:24:12 +0200
committer	Antoine Gourlay <antoine@gourlay.fr>	2015-04-22 16:01:51 +0200
commit	a3e93d95215b96740306d10a17a858f407ca39e5 (patch)
tree	e3653a59acef67d1c9e05ca7b0e77bff984c0426
parent	d2a174d27bce392329a9c5e4c7d2acee263cdb34 (diff)
download	scala-a3e93d95215b96740306d10a17a858f407ca39e5.tar.gz scala-a3e93d95215b96740306d10a17a858f407ca39e5.tar.bz2 scala-a3e93d95215b96740306d10a17a858f407ca39e5.zip