Scaladoc feature that shows implicit conversions

See https://github.com/VladUreche/scala/tree/feature/doc-implicits for the history.
See https://scala-webapps.epfl.ch/jenkins/view/scaladoc/job/scaladoc-implicits-nightly/ for nightlies.

Many thanks fly out to Adriaan for his help with implicit search!

1 files changed, 126 insertions, 1 deletions

diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala
index 45a2ad78b4..3da87bf763 100644
--- a/src/compiler/scala/tools/nsc/doc/Settings.scala
+++ b/src/compiler/scala/tools/nsc/doc/Settings.scala
@@ -87,6 +87,38 @@ class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) {
     ""
   )
 
+  val docImplicits = BooleanSetting (
+    "-implicits",
+    "Document members inherited by implicit conversions."
+  )
+
+  val docImplicitsDebug = BooleanSetting (
+    "-implicits-debug",
+    "Show debugging information for members inherited by implicit conversions."
+  )
+
+  val docImplicitsShowAll = BooleanSetting (
+    "-implicits-show-all",
+    "Show members inherited by implicit conversions that are impossible in the default scope. " +
+    "(for example conversions that require Numeric[String] to be in scope)"
+  )
+
+  val docDiagrams = BooleanSetting (
+    "-diagrams",
+    "Create inheritance diagrams for classes, traits and packages."
+  )
+
+  val docDiagramsDebug = BooleanSetting (
+    "-diagrams-debug",
+    "Show debugging information for the diagram creation process."
+  )
+
+  val docDiagramsDotPath = PathSetting (
+    "-diagrams-dot-path",
+    "The path to the dot executable used to generate the inheritance diagrams. Ex: /usr/bin/dot",
+    "dot" // by default, just pick up the system-wide dot
+  )
+
   // Somewhere slightly before r18708 scaladoc stopped building unless the
   // self-type check was suppressed.  I hijacked the slotted-for-removal-anyway
   // suppress-vt-warnings option and renamed it for this purpose.
@@ -94,9 +126,102 @@ class Settings(error: String => Unit) extends scala.tools.nsc.Settings(error) {
 
   // For improved help output.
   def scaladocSpecific = Set[Settings#Setting](
-    docformat, doctitle, docfooter, docversion, docUncompilable, docsourceurl, docgenerator
+    docformat, doctitle, docfooter, docversion, docUncompilable, docsourceurl, docgenerator, docRootContent, useStupidTypes,
+    docDiagrams, docDiagramsDebug, docDiagramsDotPath,
+    docImplicits, docImplicitsDebug, docImplicitsShowAll
   )
   val isScaladocSpecific: String => Boolean = scaladocSpecific map (_.name)
 
   override def isScaladoc = true
+
+  // unset by the testsuite, we don't need to count the entities in the model
+  var reportModel = true
+
+  /**
+   *  This is the hardcoded area of Scaladoc. This is where "undesirable" stuff gets eliminated. I know it's not pretty,
+   *  but ultimately scaladoc has to be useful. :)
+   */
+  object hardcoded {
+
+    /** The common context bounds and some humanly explanations. Feel free to add more explanations
+     *  `<root>.scala.package.Numeric` is the type class
+     *  `tparam` is the name of the type parameter it gets (this only describes type classes with 1 type param)
+     *  the function result should be a humanly-understandable description of the type class
+     */
+    val knownTypeClasses: Map[String, String => String] = Map() +
+      ("<root>.scala.package.Numeric"       -> ((tparam: String) => tparam + " is a numeric class, such as Int, Long, Float or Double")) +
+      ("<root>.scala.package.Integral"      -> ((tparam: String) => tparam + " is an integral numeric class, such as Int or Long")) +
+      ("<root>.scala.package.Fractional"    -> ((tparam: String) => tparam + " is a fractional numeric class, such as Float or Double")) +
+      ("<root>.scala.reflect.Manifest"      -> ((tparam: String) => tparam + " is accompanied by a Manifest, which is a runtime representation of its type that survives erasure")) +
+      ("<root>.scala.reflect.ClassManifest" -> ((tparam: String) => tparam + " is accompanied by a ClassManifest, which is a runtime representation of its type that survives erasure")) +
+      ("<root>.scala.reflect.OptManifest"   -> ((tparam: String) => tparam + " is accompanied by an OptManifest, which can be either a runtime representation of its type or the NoManifest, which means the runtime type is not available"))
+
+    /**
+     * Set of classes to exclude from index and diagrams
+     * TODO: Should be configurable
+     */
+    def isExcluded(qname: String) = {
+      ( ( qname.startsWith("scala.Tuple") || qname.startsWith("scala.Product") ||
+         qname.startsWith("scala.Function") || qname.startsWith("scala.runtime.AbstractFunction")
+       ) && !(
+        qname == "scala.Tuple1" || qname == "scala.Tuple2" ||
+        qname == "scala.Product" || qname == "scala.Product1" || qname == "scala.Product2" ||
+        qname == "scala.Function" || qname == "scala.Function1" || qname == "scala.Function2" ||
+        qname == "scala.runtime.AbstractFunction0" || qname == "scala.runtime.AbstractFunction1" ||
+        qname == "scala.runtime.AbstractFunction2"
+      )
+     )
+    }
+
+    /** Common conversion targets that affect any class in Scala */
+    val commonConversionTargets = List(
+      "scala.Predef.any2stringfmt",
+      "scala.Predef.any2stringadd",
+      "scala.Predef.any2ArrowAssoc",
+      "scala.Predef.any2Ensuring")
+
+    /** There's a reason all these are specialized by hand but documenting each of them is beyond the point */
+    val arraySkipConversions = List(
+      "scala.Predef.refArrayOps",
+      "scala.Predef.intArrayOps",
+      "scala.Predef.doubleArrayOps",
+      "scala.Predef.longArrayOps",
+      "scala.Predef.floatArrayOps",
+      "scala.Predef.charArrayOps",
+      "scala.Predef.byteArrayOps",
+      "scala.Predef.shortArrayOps",
+      "scala.Predef.booleanArrayOps",
+      "scala.Predef.unitArrayOps",
+      "scala.LowPriorityImplicits.wrapRefArray",
+      "scala.LowPriorityImplicits.wrapIntArray",
+      "scala.LowPriorityImplicits.wrapDoubleArray",
+      "scala.LowPriorityImplicits.wrapLongArray",
+      "scala.LowPriorityImplicits.wrapFloatArray",
+      "scala.LowPriorityImplicits.wrapCharArray",
+      "scala.LowPriorityImplicits.wrapByteArray",
+      "scala.LowPriorityImplicits.wrapShortArray",
+      "scala.LowPriorityImplicits.wrapBooleanArray",
+      "scala.LowPriorityImplicits.wrapUnitArray",
+      "scala.LowPriorityImplicits.genericWrapArray")
+
+    // included as names as here we don't have access to a Global with Definitions :(
+    def valueClassList = List("unit", "boolean", "byte", "short", "char", "int", "long", "float", "double")
+    def valueClassFilterPrefixes = List("scala.LowPriorityImplicits", "scala.Predef")
+
+    /** Dirty, dirty, dirty hack: the value params conversions can all kick in -- and they are disambiguated by priority
+     *  but showing priority in scaladoc would make no sense -- so we have to manually remove the conversions that we
+     *  know will never get a chance to kick in. Anyway, DIRTY DIRTY DIRTY! */
+    def valueClassFilter(value: String, conversionName: String): Boolean = {
+      val valueName = value.toLowerCase
+      val otherValues = valueClassList.filterNot(_ == valueName)
+
+      for (prefix <- valueClassFilterPrefixes)
+        if (conversionName.startsWith(prefix))
+          for (otherValue <- otherValues)
+            if (conversionName.startsWith(prefix + "." + otherValue))
+              return false
+
+      true
+    }
+  }
 }