From 376403266c699190882ef7c9f2a7c65c86a23a3d Mon Sep 17 00:00:00 2001 From: Vlad Ureche Date: Fri, 13 Jul 2012 15:59:01 +0200 Subject: SI-5533 Skip scaladoc packages from documentation --- src/compiler/scala/tools/nsc/doc/Settings.scala | 18 ++++++- .../scala/tools/nsc/doc/model/Entity.scala | 3 ++ .../scala/tools/nsc/doc/model/ModelFactory.scala | 59 +++++++++++----------- .../nsc/doc/model/diagram/DiagramFactory.scala | 2 +- 4 files changed, 50 insertions(+), 32 deletions(-) (limited to 'src/compiler') 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", + ":...:", + "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))() -- cgit v1.2.3