diff options
author | Felix Mulder <felix.mulder@gmail.com> | 2016-02-08 13:56:16 +0100 |
---|---|---|
committer | Felix Mulder <felix.mulder@gmail.com> | 2016-02-09 17:16:24 +0100 |
commit | f2e0616f90f934689e4892358d56221504ad2a46 (patch) | |
tree | 785c080954d9e3db23834bb7e73026349ae969e9 /src/scaladoc | |
parent | 08dd102e002b38c7c3151c0c081ee0f902e3b918 (diff) | |
download | scala-f2e0616f90f934689e4892358d56221504ad2a46.tar.gz scala-f2e0616f90f934689e4892358d56221504ad2a46.tar.bz2 scala-f2e0616f90f934689e4892358d56221504ad2a46.zip |
SI-9620: add doc annotation to hide specific conversions
This commit will introduce the doc annotation `@hideImplicitConversion`.
By specifying which conversions to hide, the user can "toggle" which
conversions are kept in the parsed entity.
This implementation is a better workaround than hardcoding which ones to
ignore when running scaladoc.
Review: @VladUreche
Diffstat (limited to 'src/scaladoc')
4 files changed, 57 insertions, 70 deletions
diff --git a/src/scaladoc/scala/tools/nsc/doc/Settings.scala b/src/scaladoc/scala/tools/nsc/doc/Settings.scala index a6a06efd1e..8a341a92d5 100644 --- a/src/scaladoc/scala/tools/nsc/doc/Settings.scala +++ b/src/scaladoc/scala/tools/nsc/doc/Settings.scala @@ -316,41 +316,6 @@ class Settings(error: String => Unit, val printMsg: String => Unit = println(_)) "scala.Predef.Ensuring", "scala.collection.TraversableOnce.alternateImplicit") - /** 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", - //TODO: remove after implementing SI-9620 - "scala.Predef._booleanArrayOps", - "scala.Predef._byteArrayOps", - "scala.Predef._charArrayOps", - "scala.Predef._doubleArrayOps", - "scala.Predef._floatArrayOps", - "scala.Predef._intArrayOps", - "scala.Predef._longArrayOps", - "scala.Predef._refArrayOps", - "scala.Predef._shortArrayOps", - "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") diff --git a/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala b/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala index f1c96636e2..707d0c469f 100644 --- a/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala +++ b/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala @@ -26,28 +26,29 @@ trait CommentFactoryBase { this: MemberLookupBase => /* Creates comments with necessary arguments */ def createComment ( - body0: Option[Body] = None, - authors0: List[Body] = List.empty, - see0: List[Body] = List.empty, - result0: Option[Body] = None, - throws0: Map[String,Body] = Map.empty, - valueParams0: Map[String,Body] = Map.empty, - typeParams0: Map[String,Body] = Map.empty, - version0: Option[Body] = None, - since0: Option[Body] = None, - todo0: List[Body] = List.empty, - deprecated0: Option[Body] = None, - note0: List[Body] = List.empty, - example0: List[Body] = List.empty, - constructor0: Option[Body] = None, - source0: Option[String] = None, - inheritDiagram0: List[String] = List.empty, - contentDiagram0: List[String] = List.empty, - group0: Option[Body] = None, - groupDesc0: Map[String,Body] = Map.empty, - groupNames0: Map[String,Body] = Map.empty, - groupPrio0: Map[String,Body] = Map.empty - ) : Comment = new Comment{ + body0: Option[Body] = None, + authors0: List[Body] = List.empty, + see0: List[Body] = List.empty, + result0: Option[Body] = None, + throws0: Map[String,Body] = Map.empty, + valueParams0: Map[String,Body] = Map.empty, + typeParams0: Map[String,Body] = Map.empty, + version0: Option[Body] = None, + since0: Option[Body] = None, + todo0: List[Body] = List.empty, + deprecated0: Option[Body] = None, + note0: List[Body] = List.empty, + example0: List[Body] = List.empty, + constructor0: Option[Body] = None, + source0: Option[String] = None, + inheritDiagram0: List[String] = List.empty, + contentDiagram0: List[String] = List.empty, + group0: Option[Body] = None, + groupDesc0: Map[String,Body] = Map.empty, + groupNames0: Map[String,Body] = Map.empty, + groupPrio0: Map[String,Body] = Map.empty, + hideImplicitConversions0: List[Body] = List.empty + ): Comment = new Comment { val body = body0 getOrElse Body(Seq.empty) val authors = authors0 val see = see0 @@ -89,8 +90,14 @@ trait CommentFactoryBase { this: MemberLookupBase => } } + override val hideImplicitConversions: List[String] = + hideImplicitConversions0 flatMap { + case Body(List(Paragraph(Chain(List(Summary(Text(e))))))) if (!e.trim.contains("\n")) => List(e) + case _ => List() + } } + private val endOfText = '\u0003' private val endOfLine = '\u000A' @@ -244,7 +251,7 @@ trait CommentFactoryBase { this: MemberLookupBase => parse0(docBody append endOfLine append marker, tags, lastTagKey, ls, inCodeBlock = true) } - case CodeBlockEndRegex(before, marker, after) :: ls => + case CodeBlockEndRegex(before, marker, after) :: ls => { if (!before.trim.isEmpty && !after.trim.isEmpty) parse0(docBody, tags, lastTagKey, before :: marker :: after :: ls, inCodeBlock = true) if (!before.trim.isEmpty) @@ -262,23 +269,27 @@ trait CommentFactoryBase { this: MemberLookupBase => case None => parse0(docBody append endOfLine append marker, tags, lastTagKey, ls, inCodeBlock = false) } + } - case SymbolTagRegex(name, sym, body) :: ls if (!inCodeBlock) => + case SymbolTagRegex(name, sym, body) :: ls if (!inCodeBlock) => { val key = SymbolTagKey(name, sym) val value = body :: tags.getOrElse(key, Nil) parse0(docBody, tags + (key -> value), Some(key), ls, inCodeBlock) + } - case SimpleTagRegex(name, body) :: ls if (!inCodeBlock) => + case SimpleTagRegex(name, body) :: ls if (!inCodeBlock) => { val key = SimpleTagKey(name) val value = body :: tags.getOrElse(key, Nil) parse0(docBody, tags + (key -> value), Some(key), ls, inCodeBlock) + } - case SingleTagRegex(name) :: ls if (!inCodeBlock) => + case SingleTagRegex(name) :: ls if (!inCodeBlock) => { val key = SimpleTagKey(name) val value = "" :: tags.getOrElse(key, Nil) parse0(docBody, tags + (key -> value), Some(key), ls, inCodeBlock) + } - case line :: ls if (lastTagKey.isDefined) => + case line :: ls if (lastTagKey.isDefined) => { val newtags = if (!line.isEmpty) { val key = lastTagKey.get val value = @@ -289,13 +300,15 @@ trait CommentFactoryBase { this: MemberLookupBase => tags + (key -> value) } else tags parse0(docBody, newtags, lastTagKey, ls, inCodeBlock) + } - case line :: ls => + case line :: ls => { if (docBody.length > 0) docBody append endOfLine docBody append line parse0(docBody, tags, lastTagKey, ls, inCodeBlock) + } - case Nil => + case Nil => { // Take the {inheritance, content} diagram keys aside, as it doesn't need any parsing val inheritDiagramTag = SimpleTagKey("inheritanceDiagram") val contentDiagramTag = SimpleTagKey("contentDiagram") @@ -383,14 +396,15 @@ trait CommentFactoryBase { this: MemberLookupBase => group0 = oneTag(SimpleTagKey("group")), groupDesc0 = allSymsOneTag(SimpleTagKey("groupdesc")), groupNames0 = allSymsOneTag(SimpleTagKey("groupname")), - groupPrio0 = allSymsOneTag(SimpleTagKey("groupprio")) + groupPrio0 = allSymsOneTag(SimpleTagKey("groupprio")), + hideImplicitConversions0 = allTags(SimpleTagKey("hideImplicitConversion")) ) for ((key, _) <- bodyTags) reporter.warning(pos, s"Tag '@${key.name}' is not recognised") com - + } } parse0(new StringBuilder(comment.size), Map.empty, None, clean(comment), inCodeBlock = false) diff --git a/src/scaladoc/scala/tools/nsc/doc/base/comment/Comment.scala b/src/scaladoc/scala/tools/nsc/doc/base/comment/Comment.scala index e5eb68d65a..183297f2c3 100644 --- a/src/scaladoc/scala/tools/nsc/doc/base/comment/Comment.scala +++ b/src/scaladoc/scala/tools/nsc/doc/base/comment/Comment.scala @@ -123,6 +123,9 @@ abstract class Comment { /** Member group priorities */ def groupPrio: Map[String,Int] + /** A list of implicit conversions to hide */ + def hideImplicitConversions: List[String] + override def toString = body.toString + "\n" + (authors map ("@author " + _.toString)).mkString("\n") + diff --git a/src/scaladoc/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala b/src/scaladoc/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala index 0264f2f99f..830d902b68 100644 --- a/src/scaladoc/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala +++ b/src/scaladoc/scala/tools/nsc/doc/model/ModelFactoryImplicitSupport.scala @@ -98,10 +98,15 @@ trait ModelFactoryImplicitSupport { // also keep empty conversions, so they appear in diagrams // conversions = conversions.filter(!_.members.isEmpty) - // Filter out specialized conversions from array - if (sym == ArrayClass) - conversions = conversions.filterNot((conv: ImplicitConversionImpl) => - hardcoded.arraySkipConversions.contains(conv.conversionQualifiedName)) + val hiddenConversions: Seq[String] = thisFactory + .comment(sym, inTpl.linkTarget, inTpl) + .map(_.hideImplicitConversions) + .getOrElse(Nil) + + conversions = conversions filterNot { conv: ImplicitConversionImpl => + hiddenConversions.contains(conv.conversionShortName) || + hiddenConversions.contains(conv.conversionQualifiedName) + } // Filter out non-sensical conversions from value types if (isPrimitiveValueType(sym.tpe_*)) |