Merged and cleaned the 'feature/inheritdoc' branch

4 files changed, 183 insertions, 32 deletions

diff --git a/src/compiler/scala/tools/nsc/ast/DocComments.scala b/src/compiler/scala/tools/nsc/ast/DocComments.scala
index 6a6379cca2..678f7b3028 100755
--- a/src/compiler/scala/tools/nsc/ast/DocComments.scala
+++ b/src/compiler/scala/tools/nsc/ast/DocComments.scala
@@ -19,6 +19,8 @@ import scala.collection.mutable
  */
 trait DocComments { self: Global =>
 
+  var cookedDocComments = Map[Symbol, String]()
+
   def reporter: Reporter
 
   /** The raw doc comment map */
@@ -50,21 +52,29 @@ trait DocComments { self: Global =>
     else sym.owner.ancestors map (sym overriddenSymbol _) filter (_ != NoSymbol)
   }
 
-  /** The raw doc comment of symbol `sym`, minus @usecase and @define sections, augmented by
+  /** The raw doc comment of symbol `sym`, minus usecase and define sections, augmented by
    *  missing sections of an inherited doc comment.
    *  If a symbol does not have a doc comment but some overridden version of it does,
    *  the doc comment of the overridden version is copied instead.
    */
-  def cookedDocComment(sym: Symbol, docStr: String = ""): String = {
-    val ownComment = if (docStr.length == 0) docComments get sym map (_.template) getOrElse ""
-                     else DocComment(docStr).template
-    superComment(sym) match {
-      case None =>
-        ownComment
-      case Some(sc) =>
-        if (ownComment == "") sc
-        else merge(sc, ownComment, sym)
-    }
+  def cookedDocComment(sym: Symbol, docStr: String = ""): String = cookedDocComments.get(sym) match {
+    case Some(comment) =>
+      comment
+    case None =>
+      val ownComment = if (docStr.length == 0) docComments get sym map (_.template) getOrElse ""
+                       else DocComment(docStr).template
+      val comment = superComment(sym) match {
+        case None =>
+          if (ownComment.indexOf("@inheritdoc") != -1)
+            reporter.warning(sym.pos, "The comment for " + sym +
+                " contains @inheritdoc, but no parent comment is available to inherit from.")
+          ownComment.replaceAllLiterally("@inheritdoc", "<invalid inheritdoc annotation>")
+        case Some(sc) =>
+          if (ownComment == "") sc
+          else expandInheritdoc(sc, merge(sc, ownComment, sym), sym)
+      }
+      cookedDocComments += (sym -> comment)
+      comment
   }
 
   /** The cooked doc comment of symbol `sym` after variable expansion, or "" if missing.
@@ -99,10 +109,18 @@ trait DocComments { self: Global =>
    */
   def useCases(sym: Symbol, site: Symbol): List[(Symbol, String, Position)] = {
     def getUseCases(dc: DocComment) = {
-      for (uc <- dc.useCases; defn <- uc.expandedDefs(sym, site)) yield
-        (defn,
-         expandVariables(merge(cookedDocComment(sym), uc.comment.raw, defn), sym, site),
-         uc.pos)
+      val fullSigComment = cookedDocComment(sym)
+      for (uc <- dc.useCases; defn <- uc.expandedDefs(sym, site)) yield {
+        // use cases comments go through a series of transformations:
+        // 1 - filling in missing sections from the full signature
+        // 2 - expanding explicit inheritance @inheritdoc tags
+        // 3 - expanding variables like $COLL
+        val useCaseCommentRaw        = uc.comment.raw
+        val useCaseCommentMerged     = merge(fullSigComment, useCaseCommentRaw, defn)
+        val useCaseCommentInheritdoc = expandInheritdoc(fullSigComment, useCaseCommentMerged, sym)
+        val useCaseCommentVariables  = expandVariables(useCaseCommentInheritdoc, sym, site)
+        (defn, useCaseCommentVariables, uc.pos)
+      }
     }
     getDocComment(sym) map getUseCases getOrElse List()
   }
@@ -201,6 +219,80 @@ trait DocComments { self: Global =>
     }
   }
 
+  /**
+   * Expand inheritdoc tags
+   *  - for the main comment we transform the inheritdoc into the super variable,
+   *  and the variable expansion can expand it further
+   *  - for the param, tparam and throws sections we must replace comments on the spot
+   *
+   * This is done separately, for two reasons:
+   * 1. It takes longer to run compared to merge
+   * 2. The inheritdoc annotation should not be used very often, as building the comment from pieces severely
+   * impacts performance
+   */
+  def expandInheritdoc(src: String, dst: String, sym: Symbol): String =
+    if (dst.indexOf("@inheritdoc") == -1)
+      dst
+    else {
+      val srcSections    = tagIndex(src)
+      val dstSections    = tagIndex(dst)
+      val srcTagMap      = sectionTagMap(src, srcSections)
+      val srcNamedParams = Map() +
+        ("@param"  -> paramDocs(src, "@param", srcSections)) +
+        ("@tparam" -> paramDocs(src, "@tparam", srcSections)) +
+        ("@throws" -> paramDocs(src, "@throws", srcSections))
+
+      val out         = new StringBuilder
+
+      def replaceInheritdoc(src: String, dst: String) =
+        if (dst.indexOf("@inheritdoc") == -1)
+          dst
+        else
+          dst.replaceAllLiterally("@inheritdoc", src)
+
+      def getSourceSection(section: (Int, Int)): String = {
+
+        def getSectionHeader = extractSectionTag(dst, section) match {
+          case param@("@param"|"@tparam"|"@throws")  => param + " "  + extractSectionParam(dst, section)
+          case other     => other
+        }
+
+        def sectionString(param: String, paramMap: Map[String, (Int, Int)]): String =
+          paramMap.get(param) match {
+            case Some(section) =>
+              // Cleanup the section tag and parameter
+              val sectionTextBounds = extractSectionText(src, section)
+              cleanupSectionText(src.substring(sectionTextBounds._1, sectionTextBounds._2))
+            case None =>
+              reporter.info(sym.pos, "The \"" + getSectionHeader + "\" annotation of the " + sym +
+                  " comment contains @inheritdoc, but the corresponding section in the parent is not defined.", true)
+              "<invalid inheritdoc annotation>"
+          }
+
+        dst.substring(section._1, section._1 + 7) match {
+          case param@("@param "|"@tparam"|"@throws") => sectionString(extractSectionParam(dst, section), srcNamedParams(param.trim))
+          case _                                     => sectionString(extractSectionTag(dst, section), srcTagMap)
+        }
+      }
+
+      def mainComment(str: String, sections: List[(Int, Int)]): String =
+        if (str.trim.length > 3)
+          str.trim.substring(3, startTag(str, sections))
+        else
+          ""
+
+      // Append main comment
+      out.append("/**")
+      out.append(replaceInheritdoc(mainComment(src, srcSections), mainComment(dst, dstSections)))
+
+      // Append sections
+      for (section <- dstSections)
+        out.append(replaceInheritdoc(getSourceSection(section), dst.substring(section._1, section._2)))
+
+      out.append("*/")
+      out.toString
+    }
+
   /** Maps symbols to the variable -> replacement maps that are defined
    *  in their doc comments
    */
diff --git a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala
index 5e5320ca9a..e35286b281 100644
--- a/src/compiler/scala/tools/nsc/doc/html/page/Template.scala
+++ b/src/compiler/scala/tools/nsc/doc/html/page/Template.scala
@@ -438,7 +438,9 @@ class Template(tpl: DocTemplateEntity) extends HtmlPage {
           if(!comment.throws.isEmpty) {
             <dt>Exceptions thrown</dt>
             <dd>{
-              val exceptionsXml: Iterable[scala.xml.NodeSeq] = (for(exception <- comment.throws ) yield <span class="cmt">{Text(exception._1) ++ bodyToHtml(exception._2)}</span> )
+              val exceptionsXml: Iterable[scala.xml.NodeSeq] =
+                for(exception <- comment.throws.toList.sortBy(_._1) ) yield
+                  <span class="cmt">{Text(exception._1) ++ bodyToHtml(exception._2)}</span>
               exceptionsXml.reduceLeft(_ ++ Text("") ++ _)
             }</dd>
           } else NodeSeq.Empty
diff --git a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala
index efa524503c..b088c643cb 100644
--- a/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala
+++ b/src/compiler/scala/tools/nsc/doc/model/comment/CommentFactory.scala
@@ -38,7 +38,7 @@ trait CommentFactory { thisFactory: ModelFactory with CommentFactory =>
     val key = (sym, inTpl)
     if (commentCache isDefinedAt key)
       Some(commentCache(key))
-    else { // not reached for use-case comments
+    else {
       val c = defineComment(sym, inTpl)
       if (c isDefined) commentCache += (sym, inTpl) -> c.get
       c
diff --git a/src/compiler/scala/tools/nsc/util/DocStrings.scala b/src/compiler/scala/tools/nsc/util/DocStrings.scala
index fbe92e5d84..f4ce6d6ef1 100755
--- a/src/compiler/scala/tools/nsc/util/DocStrings.scala
+++ b/src/compiler/scala/tools/nsc/util/DocStrings.scala
@@ -26,6 +26,14 @@ object DocStrings {
     if (start < str.length && isIdentifierPart(str charAt start)) skipIdent(str, start + 1)
     else start
 
+  /** Returns index of string `str` following `start` skipping
+   *  sequence of identifier characters.
+   */
+  def skipTag(str: String, start: Int): Int =
+    if (start < str.length && (str charAt start) == '@') skipIdent(str, start + 1)
+    else start
+
+
   /** Returns index of string `str` after `start` skipping longest
    *  sequence of space and tab characters, possibly also containing
    *  a single `*` character or the `/``**` sequence.
@@ -68,38 +76,46 @@ object DocStrings {
 
   /** Produces a string index, which is a list of ``sections'', i.e
    *  pairs of start/end positions of all tagged sections in the string.
-   *  Every section starts with a `@` and extends to the next `@`, or
-   *  to the end of the comment string, but excluding the final two
+   *  Every section starts with an at sign and extends to the next at sign,
+   *  or to the end of the comment string, but excluding the final two
    *  characters which terminate the comment.
    *
    *  Also take usecases into account - they need to expand until the next
    *  usecase or the end of the string, as they might include other sections
    *  of their own
    */
-  def tagIndex(str: String, p: Int => Boolean = (idx => true)): List[(Int, Int)] =
-    findAll(str, 0) (idx => str(idx) == '@' && p(idx)) match {
+  def tagIndex(str: String, p: Int => Boolean = (idx => true)): List[(Int, Int)] = {
+    var indices = findAll(str, 0) (idx => str(idx) == '@' && p(idx))
+    indices = mergeUsecaseSections(str, indices)
+    indices = mergeInheritdocSections(str, indices)
+
+    indices match {
       case List() => List()
-      case idxs => {
-        val idxs2 = mergeUsecaseSections(str, idxs)
-        idxs2 zip (idxs2.tail ::: List(str.length - 2))
-      }
+      case idxs   => idxs zip (idxs.tail ::: List(str.length - 2))
     }
+  }
 
   /**
    * Merge sections following an usecase into the usecase comment, so they
    * can override the parent symbol's sections
    */
   def mergeUsecaseSections(str: String, idxs: List[Int]): List[Int] = {
-    idxs.find(str.substring(_).startsWith("@usecase")) match {
-      case Some(firstUC) =>
-        val commentSections = idxs.take(idxs.indexOf(firstUC))
-        val usecaseSections = idxs.drop(idxs.indexOf(firstUC)).filter(str.substring(_).startsWith("@usecase"))
+    idxs.indexWhere(str.substring(_).startsWith("@usecase")) match {
+      case firstUCIndex if firstUCIndex != -1 =>
+        val commentSections = idxs.take(firstUCIndex)
+        val usecaseSections = idxs.drop(firstUCIndex).filter(str.substring(_).startsWith("@usecase"))
         commentSections ::: usecaseSections
-      case None =>
+      case _ =>
         idxs
     }
   }
 
+  /**
+   * Merge the inheritdoc sections, as they never make sense on their own
+   */
+  def mergeInheritdocSections(str: String, idxs: List[Int]): List[Int] =
+    idxs.filterNot(str.substring(_).startsWith("@inheritdoc"))
+
   /** Does interval `iv` start with given `tag`?
    */
   def startsWithTag(str: String, section: (Int, Int), tag: String): Boolean =
@@ -108,12 +124,11 @@ object DocStrings {
   def startsWithTag(str: String, start: Int, tag: String): Boolean =
     str.startsWith(tag, start) && !isIdentifierPart(str charAt (start + tag.length))
 
-
   /** The first start tag of a list of tag intervals,
    *  or the end of the whole comment string - 2 if list is empty
    */
   def startTag(str: String, sections: List[(Int, Int)]) = sections match {
-    case List() => str.length - 2
+    case Nil             => str.length - 2
     case (start, _) :: _ => start
   }
 
@@ -155,4 +170,46 @@ object DocStrings {
       idx
     }
   }
+
+  /** A map from the section tag to section parameters */
+  def sectionTagMap(str: String, sections: List[(Int, Int)]): Map[String, (Int, Int)] =
+    Map() ++ {
+      for (section <- sections) yield
+        extractSectionTag(str, section) -> section
+    }
+
+  /** Extract the section tag, treating the section tag as an indentifier */
+  def extractSectionTag(str: String, section: (Int, Int)): String =
+    str.substring(section._1, skipTag(str, section._1))
+
+  /** Extract the section parameter */
+  def extractSectionParam(str: String, section: (Int, Int)): String = {
+    assert(str.substring(section._1).startsWith("@param") ||
+           str.substring(section._1).startsWith("@tparam") ||
+           str.substring(section._1).startsWith("@throws"))
+
+    val start = skipWhitespace(str, skipTag(str, section._1))
+    val finish = skipIdent(str, start)
+
+    str.substring(start, finish)
+  }
+
+  /** Extract the section text, except for the tag and comment newlines */
+  def extractSectionText(str: String, section: (Int, Int)): (Int, Int) = {
+    if (str.substring(section._1).startsWith("@param") ||
+        str.substring(section._1).startsWith("@tparam") ||
+        str.substring(section._1).startsWith("@throws"))
+      (skipWhitespace(str, skipIdent(str, skipWhitespace(str, skipTag(str, section._1)))), section._2)
+    else
+      (skipWhitespace(str, skipTag(str, section._1)), section._2)
+  }
+
+  /** Cleanup section text */
+  def cleanupSectionText(str: String) = {
+    var result = str.trim.replaceAll("\n\\s+\\*\\s+", " \n")
+    while (result.endsWith("\n"))
+      result = result.substring(0, str.length - 1)
+    result
+  }
+
 }