Merge pull request #15361 from dotty-staging/scaladoc/annotations

Scaladoc annotations rework

Author: odersky

scaladoc-testcases/src/tests/annotations.scala

@@ -8,15 +8,22 @@ import scala.reflect.Enum
 
 class SomeObject(val s: String)
 
-class MyAnnotation extends StaticAnnotation
+@java.lang.annotation.Documented
+class MyAnnotation extends StaticAnnotation //expected: @Documented class MyAnnotation extends StaticAnnotation
 
-class AnnotationWithArg(val s: String, val o: SomeObject) extends StaticAnnotation
+@java.lang.annotation.Documented
+class AnnotationWithArg(val s: String, val o: SomeObject) extends StaticAnnotation //expected: @Documented class AnnotationWithArg(val s: String, val o: SomeObject) extends StaticAnnotation
 
-class AnnotationWithMultiArg(val i: Int, val s: String, val c: Char*) extends StaticAnnotation
+@java.lang.annotation.Documented
+class AnnotationWithMultiArg(val i: Int, val s: String, val c: Char*) extends StaticAnnotation //expected: @Documented class AnnotationWithMultiArg(val i: Int, val s: String, val c: Char*) extends StaticAnnotation
 
-class EnumAnnotation(val e: Enum) extends StaticAnnotation
+@java.lang.annotation.Documented
+class EnumAnnotation(val e: Enum) extends StaticAnnotation //expected: @Documented class EnumAnnotation(val e: Enum) extends StaticAnnotation
 
-class ClassAnnotation[T](val c: Class[T]) extends StaticAnnotation
+@java.lang.annotation.Documented
+class ClassAnnotation[T](val c: Class[T]) extends StaticAnnotation //expected: @Documented class ClassAnnotation[T](val c: Class[T]) extends StaticAnnotation
+
+class NotDocumentedAnnotation extends StaticAnnotation
 
 @AnnotationWithMultiArg(2, "cda", 'a', 'b', 'c') @MyAnnotation class AnnotatedClass
 
@@ -28,3 +35,5 @@ class AnnotatedMethods
   @MyAnnotation @AnnotationWithMultiArg(2, "cda", 'a', 'b', 'c') def a: String
   = ???
 }
+
+/*<-*/@NotDocumentedAnnotation/*->*/class ClassWithoutAnnotation(/*<-*/@NotDocumentedAnnotation/*->*/val a: String)

scaladoc-testcases/src/tests/specializedSignature.scala

@@ -4,11 +4,11 @@ package specializedSignature
 
 import scala.{specialized}
 
-trait AdditiveMonoid[@specialized(Int, Long, Float, Double) A]
+trait AdditiveMonoid[@specialized(Int, Long, Float, Double) A] //expected: trait AdditiveMonoid[A]
 {
   def a: A
    = ???
 
-  def b[@specialized(Int, Float) B]: B
+  def b[@specialized(Int, Float) B]: B //expected: def b[B]: B
    = ???
-}
+}

scaladoc/src/dotty/tools/scaladoc/tasty/BasicSupport.scala

@@ -40,7 +40,25 @@ trait BasicSupport:
     def documentation = parseComment(sym.docstring.getOrElse(""), sym.tree)
 
     def getAnnotations(): List[Annotation] =
-      sym.annotations.filterNot(_.symbol.packageName.startsWith("scala.annotation.internal")).map(parseAnnotation).reverse
+      // Custom annotations should be documented only if annotated by @java.lang.annotation.Documented
+      // We allow also some special cases
+      val fqNameWhitelist = Set(
+        "scala.specialized",
+        "scala.throws",
+        "scala.transient",
+        "scala.volatile",
+        "scala.annotation.experimental",
+        "scala.annotation.contructorOnly",
+        "scala.annotation.static",
+        "scala.annotation.targetName",
+        "scala.annotation.threadUnsafe",
+        "scala.annotation.varargs"
+      )
+      val documentedSymbol = summon[Quotes].reflect.Symbol.requiredClass("java.lang.annotation.Documented")
+      val annotations = sym.annotations.filter { a =>
+        a.tpe.typeSymbol.hasAnnotation(documentedSymbol) || fqNameWhitelist.contains(a.symbol.fullName)
+      }
+      annotations.map(parseAnnotation).reverse
 
     def isDeprecated(): Option[Annotation] =
       sym.annotations.find { a =>