Merge pull request #2396 from som-snytt/issue/unmoored-doc

SI-7376 Scaladoc warns when discarding local doc comments with API tags

2 files changed, 80 insertions, 8 deletions

diff --git a/test/scaladoc/run/t5527.check b/test/scaladoc/run/t5527.check
index ab2aeb2d67..235e73b5c8 100644
--- a/test/scaladoc/run/t5527.check
+++ b/test/scaladoc/run/t5527.check
@@ -1,12 +1,12 @@
-newSource1:17: warning: discarding unmoored doc comment
-          /** Testing 123 */
-          ^
-newSource1:27: warning: discarding unmoored doc comment
-        /** Calculate this result. */
+newSource1:47: warning: discarding unmoored doc comment
+        /** Document this crucial constant for posterity.
         ^
-newSource1:34: warning: discarding unmoored doc comment
-        /** Another digit is a giveaway. */
+newSource1:64: warning: discarding unmoored doc comment
+        /*************************\
         ^
+newSource1:73: warning: discarding unmoored doc comment
+        val i = 10 */** Important!
+                   ^
 [[syntax trees at end of                    parser]] // newSource1
 package <empty> {
   object UselessComments extends scala.AnyRef {
@@ -48,6 +48,26 @@ package <empty> {
     val test4 = 'a' match {
       case ('0'| '1'| '2'| '3'| '4'| '5'| '6'| '7'| '8'| '9') => true
       case _ => false
+    };
+    def test5: scala.Unit = if (true)
+      $qmark$qmark$qmark
+    else
+      ();
+    def test6 = {
+      val u = 4;
+      0.to(u).foreach(((i) => println(i)))
+    };
+    def test7 = {
+      val u = 4;
+      0.to(u).foreach(((i) => println(i)))
+    };
+    def test8 = {
+      val z = "fancy";
+      z.replace("fanc", "arts")
+    };
+    def test9 = {
+      val i = 10.$times(10);
+      assert(i.$eq$eq(100))
     }
   };
   /** comments that we should keep */
@@ -102,7 +122,11 @@ package <empty> {
         super.<init>();
         ()
       }
-    }
+    };
+    /** Get the simple value.
+       *  @return the default value
+       */
+    def value: Int = 7
   }
 }
 
diff --git a/test/scaladoc/run/t5527.scala b/test/scaladoc/run/t5527.scala
index 2449ff60c3..60ae23c1a7 100644
--- a/test/scaladoc/run/t5527.scala
+++ b/test/scaladoc/run/t5527.scala
@@ -49,6 +49,47 @@ object Test extends DirectTest {
         case _ =>
           false
       }
+
+      def test5 {
+        /** @martin is this right? It shouldn't flag me as scaladoc. */
+        if (true) ???
+      }
+
+      def test6 = {
+        /** Document this crucial constant for posterity.
+         *  Don't forget to dedoc this comment if you refactor to a local.
+         *  @author Paul Phillips
+         */
+        val u = 4
+        for (i <- 0 to u)
+          println(i)
+      }
+      def test7 = {
+        /** Some standard tags are tolerated locally and shouldn't trigger a warning.
+         *  @note Don't change this unless you know what you're doing. This means you.
+         */
+        val u = 4
+        for (i <- 0 to u)
+          println(i)
+      }
+      def test8 = {
+        /*************************\
+         * Fancy ASCII Art Block *
+         *   @author som-snytt   *
+        \*************************/
+        // this is just a local
+        val z = "fancy"
+        z replace ("fanc", "arts")
+      }
+      def test9 = {
+        val i = 10 */** Important!
+                     *  We have to multiply here!
+                     *  @author community
+                     *  @see SI-1234
+                     */
+                10
+        assert(i == 100)
+      }
     }
 
     /** comments that we should keep */
@@ -85,6 +126,13 @@ object Test extends DirectTest {
       /** class D */
       @deprecated("use ... instead", "2.10.0")
       class D
+
+      /** Get the simple value.
+       *  @return the default value
+       */
+      // an intervening line comment
+      /* I had more to say, but didn't want to pollute the scaladoc. */
+      def value: Int = 7
     }
   """.trim