diff options
Diffstat (limited to 'src/scaladoc/scala/tools/nsc/doc/base')
4 files changed, 79 insertions, 47 deletions
diff --git a/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala b/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala index f1c96636e2..d3b4bf8ff5 100644 --- a/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala +++ b/src/scaladoc/scala/tools/nsc/doc/base/CommentFactoryBase.scala @@ -26,28 +26,30 @@ 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, + shortDescription0: List[Body] = List.empty + ): Comment = new Comment { val body = body0 getOrElse Body(Seq.empty) val authors = authors0 val see = see0 @@ -89,8 +91,18 @@ trait CommentFactoryBase { this: MemberLookupBase => } } + override val shortDescription: Option[Text] = shortDescription0.lastOption collect { + case Body(List(Paragraph(Chain(List(Summary(Text(e))))))) if !e.trim.contains("\n") => Text(e) + } + + 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 +256,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,24 +274,28 @@ 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) => - val newtags = if (!line.isEmpty) { + case line :: ls if (lastTagKey.isDefined) => { + val newtags = if (!line.isEmpty || inCodeBlock) { val key = lastTagKey.get val value = ((tags get key): @unchecked) match { @@ -289,13 +305,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 +401,16 @@ 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")), + shortDescription0 = allTags(SimpleTagKey("shortDescription")) ) 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/MemberLookupBase.scala b/src/scaladoc/scala/tools/nsc/doc/base/MemberLookupBase.scala index 839598a15f..613bbd9aec 100644 --- a/src/scaladoc/scala/tools/nsc/doc/base/MemberLookupBase.scala +++ b/src/scaladoc/scala/tools/nsc/doc/base/MemberLookupBase.scala @@ -62,15 +62,15 @@ trait MemberLookupBase { syms.flatMap { case (sym, owner) => // reconstruct the original link def linkName(sym: Symbol) = { - def nameString(s: Symbol) = s.nameString + (if ((s.isModule || s.isModuleClass) && !s.isPackage) "$" else "") - val packageSuffix = if (sym.isPackage) ".package" else "" + def nameString(s: Symbol) = s.nameString + (if ((s.isModule || s.isModuleClass) && !s.hasPackageFlag) "$" else "") + val packageSuffix = if (sym.hasPackageFlag) ".package" else "" sym.ownerChain.reverse.filterNot(isRoot(_)).map(nameString(_)).mkString(".") + packageSuffix } - if (sym.isClass || sym.isModule || sym.isTrait || sym.isPackage) + if (sym.isClass || sym.isModule || sym.isTrait || sym.hasPackageFlag) findExternalLink(sym, linkName(sym)) - else if (owner.isClass || owner.isModule || owner.isTrait || owner.isPackage) + else if (owner.isClass || owner.isModule || owner.isTrait || owner.hasPackageFlag) findExternalLink(sym, linkName(owner) + "@" + externalSignature(sym)) else None @@ -183,7 +183,7 @@ trait MemberLookupBase { val member = query.substring(last_index, index).replaceAll("\\\\([#\\.])", "$1") // we want to allow javadoc-style links [[#member]] -- which requires us to remove empty members from the first - // elemnt in the list + // element in the list if ((member != "") || (!members.isEmpty)) members ::= member last_index = index + 1 diff --git a/src/scaladoc/scala/tools/nsc/doc/base/comment/Body.scala b/src/scaladoc/scala/tools/nsc/doc/base/comment/Body.scala index ac5fec80b3..2524fb75fb 100644 --- a/src/scaladoc/scala/tools/nsc/doc/base/comment/Body.scala +++ b/src/scaladoc/scala/tools/nsc/doc/base/comment/Body.scala @@ -11,8 +11,9 @@ package comment import scala.collection._ /** A body of text. A comment has a single body, which is composed of - * at least one block. Inside every body is exactly one summary (see - * [[scala.tools.nsc.doc.model.comment.Summary]]). */ + * at least one block. Inside every body is exactly one summary. + * @see [[Summary]] + */ final case class Body(blocks: Seq[Block]) { /** The summary text of the comment body. */ @@ -73,9 +74,8 @@ object EntityLink { def unapply(el: EntityLink): Option[(Inline, LinkTo)] = Some((el.title, el.link)) } final case class HtmlTag(data: String) extends Inline { - private val Pattern = """(?ms)\A<(/?)(.*?)[\s>].*\z""".r private val (isEnd, tagName) = data match { - case Pattern(s1, s2) => + case HtmlTag.Pattern(s1, s2) => (! s1.isEmpty, Some(s2.toLowerCase)) case _ => (false, None) @@ -85,8 +85,13 @@ final case class HtmlTag(data: String) extends Inline { isEnd && tagName == open.tagName } + def close = tagName collect { + case name if !HtmlTag.TagsNotToClose(name) && !data.endsWith(s"</$name>") => HtmlTag(s"</$name>") + } +} +object HtmlTag { + private val Pattern = """(?ms)\A<(/?)(.*?)[\s>].*\z""".r private val TagsNotToClose = Set("br", "img") - def close = tagName collect { case name if !TagsNotToClose(name) => HtmlTag(s"</$name>") } } /** The summary of a comment, usually its first sentence. There must be exactly one summary per body. */ 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..55527e43a1 100644 --- a/src/scaladoc/scala/tools/nsc/doc/base/comment/Comment.scala +++ b/src/scaladoc/scala/tools/nsc/doc/base/comment/Comment.scala @@ -12,7 +12,7 @@ import scala.collection._ /** A Scaladoc comment and all its tags. * - * '''Note:''' the only instantiation site of this class is in [[CommentFactory]]. + * '''Note:''' the only instantiation site of this class is in [[model.CommentFactory]]. * * @author Manohar Jonnalagedda * @author Gilles Dubochet */ @@ -21,7 +21,7 @@ abstract class Comment { /** The main body of the comment that describes what the entity does and is. */ def body: Body - private def closeHtmlTags(inline: Inline) = { + private def closeHtmlTags(inline: Inline): Inline = { val stack = mutable.ListBuffer.empty[HtmlTag] def scan(i: Inline) { i match { @@ -47,9 +47,10 @@ abstract class Comment { Chain(List(inline) ++ stack.reverse) } - /** A shorter version of the body. Usually, this is the first sentence of the body. */ + /** A shorter version of the body. Either from `@shortDescription` or the + * first sentence of the body. */ def short: Inline = { - body.summary match { + shortDescription orElse body.summary match { case Some(s) => closeHtmlTags(s) case _ => @@ -62,7 +63,7 @@ abstract class Comment { /** A list of other resources to see, including links to other entities or * to external documentation. The empty list is used when no other resource - * is mentionned. */ + * is mentioned. */ def see: List[Body] /** A description of the result of the entity. Typically, this provides additional @@ -123,6 +124,12 @@ abstract class Comment { /** Member group priorities */ def groupPrio: Map[String,Int] + /** A list of implicit conversions to hide */ + def hideImplicitConversions: List[String] + + /** A short description used in the entity-view and search results */ + def shortDescription: Option[Text] + override def toString = body.toString + "\n" + (authors map ("@author " + _.toString)).mkString("\n") + |