chore: introduce scala.annotation.documented

Author: hamzaremmal

library/src/scala/annotation/constructorOnly.scala

@@ -20,4 +20,6 @@ import scala.annotation.meta.*
  *  class fields. But it is checked that the field is eliminated before code
  *  is generated.
  */
-@param @field class constructorOnly extends scala.annotation.StaticAnnotation
+@param @field
+@documented
+class constructorOnly extends scala.annotation.StaticAnnotation

library/src/scala/annotation/documented.scala

@@ -0,0 +1,10 @@
+package scala.annotation
+
+// TODO: Write the actual scaladoc of this annotation
+
+// The annotation from Java is a simple hack as both have the same semantic
+// meaning, only this one should be used by Scala code and the second
+// annotation by Java Code
+// @documented (TODO: can we make it work without breaking the cycle detection algorithm?)
+@java.lang.annotation.Documented
+final class documented extends StaticAnnotation

library/src/scala/annotation/experimental.scala

@@ -5,5 +5,6 @@ package scala.annotation
  *  @see [[https://dotty.epfl.ch/docs/reference/other-new-features/experimental-defs]]
  *  @syntax markdown
  */
+@documented
 final class experimental(message: String) extends StaticAnnotation:
   def this() = this("")

library/src/scala/annotation/static.scala

@@ -10,4 +10,5 @@ import scala.annotation.meta.*
 @beanSetter
 @param
 @setter
+@documented
 final class static extends StaticAnnotation

library/src/scala/annotation/targetName.scala

@@ -5,4 +5,5 @@ package scala.annotation
  *  definition, its implementation will use the name `extname` instead of
  *  the regular name.
  */
+@documented
 final class targetName(name: String) extends StaticAnnotation

library/src/scala/annotation/threadUnsafe.scala

@@ -4,4 +4,5 @@ package scala.annotation
  *  When this annotation is used, the initialization of the lazy val will use a
  *  faster mechanism which is not thread-safe.
  */
+@documented
 final class threadUnsafe extends StaticAnnotation

library/src/scala/annotation/varargs.scala

@@ -18,4 +18,5 @@ import scala.language.`2.13`
  *  Java varargs-style forwarder method for interop. This annotation can
  *  only be applied to methods with repeated parameters.
  */
+@documented
 final class varargs extends scala.annotation.StaticAnnotation

library/src/scala/caps/package.scala

@@ -1,7 +1,7 @@
 package scala
 package caps
 
-import annotation.{experimental, compileTimeOnly, retainsCap}
+import annotation.{experimental, documented, compileTimeOnly, retainsCap}
 
 /**
  * Base trait for classes that represent capabilities in the
@@ -117,10 +117,10 @@ final class reserve extends annotation.StaticAnnotation
 /** Allowed only for source versions up to 3.7:
  *  An annotation on parameters `x` stating that the method's body makes
  *  use of the reach capability `x*`. Consequently, when calling the method
- *  we need to charge the deep capture set of the actual argiment to the
+ *  we need to charge the deep capture set of the actual argument to the
  *  environment.
  */
-@experimental
+@experimental @documented
 final class use extends annotation.StaticAnnotation
 
 /** A trait that used to allow expressing existential types. Replaced by

library/src/scala/specialized.scala

@@ -14,6 +14,8 @@ package scala
 
 import scala.language.`2.13`
 
+import scala.annotation.documented
+
 import Specializable._
 
 /** Annotate type parameters on which code should be automatically
@@ -30,6 +32,7 @@ import Specializable._
  */
 // class tspecialized[T](group: Group[T]) extends scala.annotation.StaticAnnotation {
 
+@documented
 final class specialized(group: SpecializedGroup) extends scala.annotation.StaticAnnotation {
   def this(types: Specializable*) = this(new Group(types.toList))
   def this() = this(Primitives)

library/src/scala/throws.scala

@@ -14,6 +14,8 @@ package scala
 
 import scala.language.`2.13`
 
+import scala.annotation.documented
+
 /**
  * Annotation for specifying the exceptions thrown by a method.
  * For example:
@@ -25,6 +27,7 @@ import scala.language.`2.13`
  * }
  * }}}
  */
+@documented
 final class throws[T <: Throwable](cause: String = "") extends scala.annotation.StaticAnnotation {
   def this(clazz: Class[T]) = this("")
 }