Merge pull request scala#4464 from gourlaysama/wip/scaladoc-deprecated

Vlad Ureche · Vlad Ureche · commit d063dd32098f · 2015-04-22T21:30:07.000+02:00
SI-4476 add an index of deprecated members to scaladoc
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
+    }
+  }
 }

Original file line number	Diff line number	Diff line change
`@@ -11,4 +11,6 @@ trait Index {`
`11`	`11`	`type SymbolMap = SortedMap[String, SortedSet[model.MemberEntity]]`
`12`	`12`
`13`	`13`	`def firstLetterIndex: Map[Char, SymbolMap]`
	`14`	`+`
	`15`	`+ def hasDeprecatedMembers: Boolean`
`14`	`16`	`}`
Original file line number	Diff line number	Diff line change
`@@ -14,10 +14,12 @@ object IndexModelFactory {`
`14`	`14`
`15`	`15`	`def makeIndex(universe: Universe): Index = new Index {`
`16`	`16`
`17`		`- lazy val firstLetterIndex: Map[Char, SymbolMap] = {`
	`17`	`+ lazy val (firstLetterIndex, hasDeprecatedMembers): (Map[Char, SymbolMap], Boolean) = {`
`18`	`18`
`19`	`19`	`object result extends mutable.HashMap[Char,SymbolMap] {`
`20`	`20`
	`21`	`+ var deprecated = false`
	`22`	`+`
`21`	`23`	`/* symbol name ordering */`
`22`	`24`	`implicit def orderingMap = math.Ordering.String`
`23`	`25`
`@@ -32,6 +34,8 @@ object IndexModelFactory {`
`32`	`34`	`val members = letter.get(d.name).getOrElse {`
`33`	`35`	`SortedSet.empty[MemberEntity](Ordering.by { _.toString })`
`34`	`36`	`} + d`
	`37`	`+ if (!deprecated && members.find(_.deprecation.isDefined).isDefined)`
	`38`	`+ deprecated = true`
`35`	`39`	`this(firstLetter) = letter + (d.name -> members)`
`36`	`40`	`}`
`37`	`41`	`}`
`@@ -50,7 +54,7 @@ object IndexModelFactory {`
`50`	`54`
`51`	`55`	`gather(universe.rootPackage)`
`52`	`56`
`53`		`- result.toMap`
	`57`	`+ (result.toMap, result.deprecated)`
`54`	`58`	`}`
`55`	`59`	`}`
`56`	`60`	`}`
Original file line number	Diff line number	Diff line change
`@@ -71,7 +71,7 @@ object Test extends Properties("Index") {`
`71`	`71`	`case None => false`
`72`	`72`	`}`
`73`	`73`	`}`
`74`		`- property("browser contants a script element") = {`
	`74`	`+ property("browser contains a script element") = {`
`75`	`75`	`createIndex("src/scaladoc/scala/tools/nsc/doc/html/page/Index.scala") match {`
`76`	`76`	`case Some(index) =>`
`77`	`77`	`(index.browser \ "script").size == 1`
`@@ -86,4 +86,10 @@ object Test extends Properties("Index") {`
`86`	`86`	`case None => false`
`87`	`87`	`}`
`88`	`88`	`}`
	`89`	`+ property("index should report if there are deprecated members") = {`
	`90`	`+ createIndex("test/scaladoc/resources/SI-4476.scala") match {`
	`91`	`+ case Some(indexPage) => indexPage.index.hasDeprecatedMembers`
	`92`	`+ case None => false`
	`93`	`+ }`
	`94`	`+ }`
`89`	`95`	`}`