SI-5533 Skip scaladoc packages from documentation

8 files changed, 98 insertions, 42 deletions

diff --git a/src/compiler/scala/tools/nsc/doc/Settings.scala b/src/compiler/scala/tools/nsc/doc/Settings.scala
index 12b27387a7..7cb539feee 100644
--- a/src/compiler/scala/tools/nsc/doc/Settings.scala
+++ b/src/compiler/scala/tools/nsc/doc/Settings.scala
@@ -176,6 +176,13 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_))
     "Avoid warnings for ambiguous and incorrect links."
   )
 
+  val docSkipPackages = StringSetting (
+    "-skip-packages",
+    "<package1>:...:<packageN>",
+    "A colon-delimited list of fully qualified package names that will be skipped from scaladoc.",
+    ""
+  )
+
   // 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.
@@ -188,7 +195,7 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_))
     docDiagramsDotTimeout, docDiagramsDotRestart,
     docImplicits, docImplicitsDebug, docImplicitsShowAll,
     docDiagramsMaxNormalClasses, docDiagramsMaxImplicitClasses,
-    docNoPrefixes, docNoLinkWarnings, docRawOutput
+    docNoPrefixes, docNoLinkWarnings, docRawOutput, docSkipPackages
   )
   val isScaladocSpecific: String => Boolean = scaladocSpecific map (_.name)
 
@@ -197,6 +204,15 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_))
   // set by the testsuite, when checking test output
   var scaladocQuietRun = false
 
+  lazy val skipPackageNames =
+    if (docSkipPackages.value == "")
+      Set[String]()
+    else
+      docSkipPackages.value.toLowerCase.split(':').toSet
+
+  def skipPackage(qname: String) =
+    skipPackageNames(qname.toLowerCase)
+
   /**
    *  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. :)
diff --git a/src/compiler/scala/tools/nsc/doc/model/Entity.scala b/src/compiler/scala/tools/nsc/doc/model/Entity.scala
index 626c1500f1..d9758c6f2f 100644
--- a/src/compiler/scala/tools/nsc/doc/model/Entity.scala
+++ b/src/compiler/scala/tools/nsc/doc/model/Entity.scala
@@ -97,6 +97,9 @@ trait TemplateEntity extends Entity {
   /** Whether documentation is available for this template. */
   def isDocTemplate: Boolean
 
+  /** Whether documentation is available for this template. */
+  def isNoDocMemberTemplate: Boolean
+
   /** Whether this template is a case class. */
   def isCaseClass: Boolean
 
diff --git a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
index d3d229d848..2fec832db8 100644
--- a/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
+++ b/src/compiler/scala/tools/nsc/doc/model/ModelFactory.scala
@@ -106,6 +106,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
     def isObject = sym.isModule && !sym.isPackage
     def isCaseClass = sym.isCaseClass
     def isRootPackage = false
+    def isNoDocMemberTemplate = false
     def selfType = if (sym.thisSym eq sym) None else Some(makeType(sym.thisSym.typeOfThis, this))
   }
 
@@ -270,6 +271,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
     // no templates cache for this class, each owner gets its own instance
     override def isTemplate = true
     def isDocTemplate = false
+    override def isNoDocMemberTemplate = true
     lazy val definitionName = optimize(inDefinitionTemplates.head.qualifiedName + "." + name)
   }
 
@@ -518,7 +520,29 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
   }
   /* ============== MAKER METHODS ============== */
 
-  /** */
+  /** This method makes it easier to work with the different kinds of symbols created by scalac
+   *
+   * Okay, here's the explanation of what happens. The code:
+   *
+   * package foo {
+   *   object `package` {
+   *     class Bar
+   *   }
+   * }
+   *
+   * will yield this Symbol structure:
+   *
+   * +---------------+         +--------------------------+
+   * | package foo#1 ----(1)---> module class foo#2       |
+   * +---------------+         | +----------------------+ |         +-------------------------+
+   *                           | | package object foo#3 ------(1)---> module class package#4  |
+   *                           | +----------------------+ |         | +---------------------+ |
+   *                           +--------------------------+         | | class package$Bar#5 | |
+   *                                                                | +---------------------+ |
+   *                                                                +-------------------------+
+   * (1) sourceModule
+   * (2) you get out of owners with .owner
+   */
   def normalizeTemplate(aSym: Symbol): Symbol = aSym match {
     case null | rootMirror.EmptyPackage | NoSymbol =>
       normalizeTemplate(RootPackage)
@@ -528,8 +552,6 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
       normalizeTemplate(aSym.owner)
     case _ if aSym.isModuleClass =>
       normalizeTemplate(aSym.sourceModule)
-    // case t: ThisType =>
-    //   t.
     case _ =>
       aSym
   }
@@ -720,6 +742,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
           override def useCaseOf = _useCaseOf
         })
       else if (bSym.isPackage && !modelFinished)
+        if (settings.skipPackage(makeQualifiedName(bSym))) None else
         inTpl match {
           case inPkg: PackageImpl => modelCreation.createTemplate(bSym, inTpl) match {
             case p: PackageImpl if droppedPackages contains p => None
@@ -933,33 +956,8 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
     //path.mkString(".")
   }
 
-  def normalizeOwner(aSym: Symbol): Symbol =
-    /*
-     * Okay, here's the explanation of what happens. The code:
-     *
-     * package foo {
-     *   object `package` {
-     *     class Bar
-     *   }
-     * }
-     *
-     * will yield this Symbol structure:
-     *
-     * +---------------+         +--------------------------+
-     * | package foo#1 ----(1)---> module class foo#2       |
-     * +---------------+         | +----------------------+ |         +-------------------------+
-     *                           | | package object foo#3 ------(1)---> module class package#4  |
-     *                           | +----------------------+ |         | +---------------------+ |
-     *                           +--------------------------+         | | class package$Bar#5 | |
-     *                                                                | +---------------------+ |
-     *                                                                +-------------------------+
-     * (1) sourceModule
-     * (2) you get out of owners with .owner
-     */
-    normalizeTemplate(aSym)
-
   def inOriginalOwner(aSym: Symbol, inTpl: TemplateImpl): Boolean =
-    normalizeOwner(aSym.owner) == normalizeOwner(inTpl.sym)
+    normalizeTemplate(aSym.owner) == normalizeTemplate(inTpl.sym)
 
   def templateShouldDocument(aSym: Symbol, inTpl: TemplateImpl): Boolean =
     (aSym.isClass || aSym.isModule || aSym == AnyRefClass) &&
@@ -968,7 +966,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
     // either it's inside the original owner or we can document it later:
     (!inOriginalOwner(aSym, inTpl) || (aSym.isPackageClass || (aSym.sourceFile != null)))
 
-  def membersShouldDocument(sym: Symbol, inTpl: TemplateImpl) =
+  def membersShouldDocument(sym: Symbol, inTpl: TemplateImpl) = {
     // pruning modules that shouldn't be documented
     // Why Symbol.isInitialized? Well, because we need to avoid exploring all the space available to scaladoc
     // from the classpath -- scaladoc is a hog, it will explore everything starting from the root package unless we
@@ -981,6 +979,7 @@ class ModelFactory(val global: Global, val settings: doc.Settings) {
     (!sym.isConstructor || sym.owner == inTpl.sym) &&
     // If the @bridge annotation overrides a normal member, show it
     !isPureBridge(sym)
+  }
 
   def isEmptyJavaObject(aSym: Symbol): Boolean =
     aSym.isModule && aSym.isJavaDefined &&
diff --git a/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala b/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala
index 9b56509623..e0f6d42a68 100644
--- a/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala
+++ b/src/compiler/scala/tools/nsc/doc/model/diagram/DiagramFactory.scala
@@ -142,7 +142,7 @@ trait DiagramFactory extends DiagramDirectiveParser {
           }
 
           mapNodes += node -> (
-            if (node.inTemplate == pack)
+            if (node.inTemplate == pack && !node.isNoDocMemberTemplate)
               NormalNode(node.resultType, Some(node))()
             else
               OutsideNode(node.resultType, Some(node))()
diff --git a/src/partest/scala/tools/partest/ScaladocModelTest.scala b/src/partest/scala/tools/partest/ScaladocModelTest.scala
index fb93e98726..fc540f83fe 100644
--- a/src/partest/scala/tools/partest/ScaladocModelTest.scala
+++ b/src/partest/scala/tools/partest/ScaladocModelTest.scala
@@ -11,8 +11,9 @@ import scala.tools.nsc._
 import scala.tools.nsc.util.CommandLineParser
 import scala.tools.nsc.doc.{Settings, DocFactory, Universe}
 import scala.tools.nsc.doc.model._
-import scala.tools.nsc.reporters.ConsoleReporter
+import scala.tools.nsc.doc.model.diagram._
 import scala.tools.nsc.doc.model.comment._
+import scala.tools.nsc.reporters.ConsoleReporter
 
 /** A class for testing scaladoc model generation
  *   - you need to specify the code in the `code` method
@@ -181,5 +182,13 @@ abstract class ScaladocModelTest extends DirectTest {
       }
       countLinks(c.body)
     }
+
+    def testDiagram(doc: DocTemplateEntity, diag: Option[Diagram], nodes: Int, edges: Int) = {
+      assert(diag.isDefined, doc.qualifiedName + " diagram missing")
+      assert(diag.get.nodes.length == nodes,
+             doc.qualifiedName + "'s diagram: node count " + diag.get.nodes.length + " == " + nodes)
+      assert(diag.get.edges.map(_._2.length).sum == edges,
+             doc.qualifiedName + "'s diagram: edge count " + diag.get.edges.length + " == " + edges)
+    }
   }
 }
diff --git a/test/scaladoc/run/SI-3314-diagrams.scala b/test/scaladoc/run/SI-3314-diagrams.scala
index 0b07e4c5bd..050c6e7f48 100644
--- a/test/scaladoc/run/SI-3314-diagrams.scala
+++ b/test/scaladoc/run/SI-3314-diagrams.scala
@@ -1,5 +1,4 @@
 import scala.tools.nsc.doc.model._
-import scala.tools.nsc.doc.model.diagram._
 import scala.tools.partest.ScaladocModelTest
 
 object Test extends ScaladocModelTest {
@@ -17,14 +16,6 @@ object Test extends ScaladocModelTest {
     val base = rootPackage._package("scala")._package("test")._package("scaladoc")
 
     val diagrams = base._package("diagrams")
-    def testDiagram(doc: DocTemplateEntity, diag: Option[Diagram], nodes: Int, edges: Int) = {
-      assert(diag.isDefined, doc.qualifiedName + " diagram missing")
-      assert(diag.get.nodes.length == nodes,
-             doc.qualifiedName + "'s diagram: node count " + diag.get.nodes.length + " == " + nodes)
-      assert(diag.get.edges.length == edges,
-             doc.qualifiedName + "'s diagram: edge count " + diag.get.edges.length + " == " + edges)
-    }
-
     val templates = List(diagrams._trait("WeekDayTraitWithDiagram"), diagrams._class("WeekDayClassWithDiagram"), diagrams._object("WeekDayObjectWithDiagram"))
 
     for (template <- templates) {
diff --git a/test/scaladoc/run/SI-5533.check b/test/scaladoc/run/SI-5533.check
new file mode 100644
index 0000000000..619c56180b
--- /dev/null
+++ b/test/scaladoc/run/SI-5533.check
@@ -0,0 +1 @@
+Done.
diff --git a/test/scaladoc/run/SI-5533.scala b/test/scaladoc/run/SI-5533.scala
new file mode 100644
index 0000000000..e7b5f57860
--- /dev/null
+++ b/test/scaladoc/run/SI-5533.scala
@@ -0,0 +1,37 @@
+import scala.tools.nsc.doc.model._
+import scala.tools.partest.ScaladocModelTest
+
+object Test extends ScaladocModelTest {
+
+  // Working around the fact that usecases have the form Coll[T] and not Coll[T, U], as required by Map
+  override def code = """
+      package a {
+        class A { class Z }
+        class C extends b.B { class X extends Y }
+      }
+
+      package b {
+        /** @contentDiagram */
+        class B extends a.A { class Y extends Z }
+        /** @contentDiagram */
+        class D extends a.C { class V extends X }
+      }
+  """
+
+  // no need for special settings
+  def scaladocSettings = "-diagrams -skip-packages a"
+
+  def testModel(rootPackage: Package) = {
+    // get the quick access implicit defs in scope (_package(s), _class(es), _trait(s), object(s) _method(s), _value(s))
+    import access._
+
+    // just need to check the member exists, access methods will throw an error if there's a problem
+    assert(!rootPackage.templates.exists(_.name == "a"), "package a should not exist in the root package")
+    assert(rootPackage.templates.exists(_.name == "b"),  "package b should exist in the root package")
+    val b = rootPackage._package("b")
+    val B = b._class("B")
+    val D = b._class("D")
+    testDiagram(B, B.contentDiagram, 2, 1)
+    testDiagram(D, D.contentDiagram, 2, 1)
+  }
+}
\ No newline at end of file