Fixed SI-5599

Eliminated the spurious warnings and made the code easier to follow.

1 files changed, 33 insertions, 26 deletions

diff --git a/src/compiler/scala/tools/nsc/ast/DocComments.scala b/src/compiler/scala/tools/nsc/ast/DocComments.scala
index 678f7b3028..d3f4688d4b 100755
--- a/src/compiler/scala/tools/nsc/ast/DocComments.scala
+++ b/src/compiler/scala/tools/nsc/ast/DocComments.scala
@@ -229,31 +229,36 @@ trait DocComments { self: Global =>
    * 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
+   *
+   * @param parent The source (or parent) comment
+   * @param child  The child (overriding member or usecase) comment
+   * @param sym    The child symbol
+   * @return       The child comment with the inheritdoc sections expanded
    */
-  def expandInheritdoc(src: String, dst: String, sym: Symbol): String =
-    if (dst.indexOf("@inheritdoc") == -1)
-      dst
+  def expandInheritdoc(parent: String, child: String, sym: Symbol): String =
+    if (child.indexOf("@inheritdoc") == -1)
+      child
     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 parentSections    = tagIndex(parent)
+      val childSections     = tagIndex(child)
+      val parentTagMap      = sectionTagMap(parent, parentSections)
+      val parentNamedParams = Map() +
+        ("@param"  -> paramDocs(parent, "@param", parentSections)) +
+        ("@tparam" -> paramDocs(parent, "@tparam", parentSections)) +
+        ("@throws" -> paramDocs(parent, "@throws", parentSections))
 
       val out         = new StringBuilder
 
-      def replaceInheritdoc(src: String, dst: String) =
-        if (dst.indexOf("@inheritdoc") == -1)
-          dst
-        else
-          dst.replaceAllLiterally("@inheritdoc", src)
+      def replaceInheritdoc(childSection: String, parentSection: => String) =
+        if (childSection.indexOf("@inheritdoc") == -1)
+          childSection
+        else 
+          childSection.replaceAllLiterally("@inheritdoc", parentSection)
 
-      def getSourceSection(section: (Int, Int)): String = {
+      def getParentSection(section: (Int, Int)): String = {
 
-        def getSectionHeader = extractSectionTag(dst, section) match {
-          case param@("@param"|"@tparam"|"@throws")  => param + " "  + extractSectionParam(dst, section)
+        def getSectionHeader = extractSectionTag(child, section) match {
+          case param@("@param"|"@tparam"|"@throws")  => param + " "  + extractSectionParam(child, section)
           case other     => other
         }
 
@@ -261,17 +266,19 @@ trait DocComments { self: Global =>
           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))
+              val sectionTextBounds = extractSectionText(parent, section)
+              cleanupSectionText(parent.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)
+        child.substring(section._1, section._1 + 7) match {
+          case param@("@param "|"@tparam"|"@throws") => 
+            sectionString(extractSectionParam(child, section), parentNamedParams(param.trim))
+          case _                                     => 
+            sectionString(extractSectionTag(child, section), parentTagMap)
         }
       }
 
@@ -283,11 +290,11 @@ trait DocComments { self: Global =>
 
       // Append main comment
       out.append("/**")
-      out.append(replaceInheritdoc(mainComment(src, srcSections), mainComment(dst, dstSections)))
+      out.append(replaceInheritdoc(mainComment(child, childSections), mainComment(parent, parentSections)))
 
       // Append sections
-      for (section <- dstSections)
-        out.append(replaceInheritdoc(getSourceSection(section), dst.substring(section._1, section._2)))
+      for (section <- childSections)
+        out.append(replaceInheritdoc(child.substring(section._1, section._2), getParentSection(section)))
 
       out.append("*/")
       out.toString