1 files changed, 38 insertions, 2 deletions
diff --git a/src/scaladoc/scala/tools/nsc/doc/ScaladocAnalyzer.scala b/src/scaladoc/scala/tools/nsc/doc/ScaladocAnalyzer.scala
index bf6d6ffed7..99a6ab9e3e 100644
--- a/src/scaladoc/scala/tools/nsc/doc/ScaladocAnalyzer.scala
+++ b/src/scaladoc/scala/tools/nsc/doc/ScaladocAnalyzer.scala
@@ -9,7 +9,6 @@ package doc
 import scala.tools.nsc.ast.parser.{ SyntaxAnalyzer, BracePatch }
 import scala.reflect.internal.Chars._
 import symtab._
-import reporters.Reporter
 import typechecker.Analyzer
 import scala.reflect.internal.util.{ BatchSourceFile, RangePosition }
 
@@ -154,9 +153,46 @@ abstract class ScaladocSyntaxAnalyzer[G <: Global](val global: G) extends Syntax
     private var docPos: Position         = NoPosition  // last doc comment position
     private var inDocComment             = false
 
+    private lazy val unmooredParser = {                // minimalist comment parser
+      import scala.tools.nsc.doc.base.{comment => _, _}
+      new {
+        val global: Global = ScaladocSyntaxAnalyzer.this.global
+      } with CommentFactoryBase with MemberLookupBase {
+        import global.{ settings, Symbol }
+        def parseComment(comment: DocComment) = {
+          val nowarnings = settings.nowarn.value
+          settings.nowarn.value = true
+          try parseAtSymbol(comment.raw, comment.raw, comment.pos)
+          finally settings.nowarn.value = nowarnings
+        }
+
+        override def internalLink(sym: Symbol, site: Symbol): Option[LinkTo] = None
+        override def chooseLink(links: List[LinkTo]): LinkTo = links.headOption orNull
+        override def toString(link: LinkTo): String = "No link"
+        override def findExternalLink(sym: Symbol, name: String): Option[LinkToExternal] = None
+        override def warnNoLink: Boolean = false
+      }
+    }
+
+    /**
+     * Warn when discarding buffered doc at the end of a block.
+     * This mechanism doesn't warn about arbitrary unmoored doc.
+     * Also warn under -Xlint, but otherwise only warn in the presence of suspicious
+     * tags that appear to be documenting API.  Warnings are suppressed while parsing
+     * the local comment so that comments of the form `[at] Martin` will not trigger a warning.
+     * In addition, tags for `todo`, `note` and `example` are ignored.
+     */
     override def discardDocBuffer() = {
+      import scala.tools.nsc.doc.base.comment.Comment
       val doc = flushDoc
-      if (doc ne null)
+      // tags that make a local double-star comment look unclean, as though it were API
+      def unclean(comment: Comment): Boolean = {
+        import comment._
+        authors.nonEmpty || result.nonEmpty || throws.nonEmpty || valueParams.nonEmpty ||
+        typeParams.nonEmpty || version.nonEmpty || since.nonEmpty
+      }
+      def isDirty = unclean(unmooredParser parseComment doc)
+      if ((doc ne null) && (settings.lint || isDirty))
         unit.warning(docPos, "discarding unmoored doc comment")
     }