SI-5533 Skip scaladoc packages from documentation

4 files changed, 50 insertions, 32 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))()