Merge pull request #10590 from dotty-staging/improve-quoted-runtime-docs

Improve quoted.runtime docs

Author: smarter

library/src/scala/quoted/runtime/Expr.scala

@@ -6,16 +6,24 @@ import scala.annotation.{Annotation, compileTimeOnly}
 @compileTimeOnly("Illegal reference to `scala.quoted.runtime.Expr`")
 object Expr:
 
-  /** A term quote is desugared by the compiler into a call to this method */
+  /** A term quote is desugared by the compiler into a call to this method
+   *
+   *  Calling this method in source has undefined behaviour at compile-time
+   */
   @compileTimeOnly("Illegal reference to `scala.quoted.runtime.Expr.quote`")
   def quote[T](x: T): Quotes ?=> scala.quoted.Expr[T] = ???
 
-  /** A term splice is desugared by the compiler into a call to this method */
+  /** A term splice is desugared by the compiler into a call to this method
+   *
+   *  Calling this method in source has undefined behaviour at compile-time
+   */
   @compileTimeOnly("Illegal reference to `scala.quoted.runtime.Expr.splice`")
   def splice[T](x: Quotes ?=> scala.quoted.Expr[T]): T = ???
 
   /** A term splice nested within a quote is desugared by the compiler into a call to this method.
-  *  `ctx` is the `Quotes` that the quote of this splice uses.
-  */
+   *  `ctx` is the `Quotes` that the quote of this splice uses.
+   *
+   *  Calling this method in source has undefined behaviour at compile-time
+   */
   @compileTimeOnly("Illegal reference to `scala.quoted.runtime.Expr.nestedSplice`")
   def nestedSplice[T](q: Quotes)(x: q.Nested ?=> scala.quoted.Expr[T]): T = ???

library/src/scala/quoted/runtime/Patterns.scala

@@ -5,23 +5,38 @@ import scala.annotation.{Annotation, compileTimeOnly}
 @compileTimeOnly("Illegal reference to `scala.quoted.runtime.Patterns`")
 object Patterns {
 
-  /** A splice in a quoted pattern is desugared by the compiler into a call to this method */
+  /** A splice in a quoted pattern is desugared by the compiler into a call to this method.
+   *
+   *  Calling this method in source has undefined behaviour at compile-time
+   */
   @compileTimeOnly("Illegal reference to `scala.quoted.runtime.Patterns.patternHole`")
   def patternHole[T]: T = ???
 
+  /** A higher order splice in a quoted pattern is desugared by the compiler into a call to this method.
+   *
+   *  Calling this method in source has undefined behaviour at compile-time
+   */
   @compileTimeOnly("Illegal reference to `scala.quoted.runtime.Patterns.patternHigherOrderHole`")
-  /** A higher order splice in a quoted pattern is desugared by the compiler into a call to this method */
   def patternHigherOrderHole[U](pat: Any, args: Any*): U = ???
 
+  /** A higher order splice in a quoted pattern is desugared by the compiler into a call to this method.
+   *
+   *  Calling this method in source has undefined behaviour at compile-time
+   */
   @compileTimeOnly("Illegal reference to `scala.quoted.runtime.Patterns.higherOrderHole`")
-  /** A higher order splice in a quoted pattern is desugared by the compiler into a call to this method */
   def higherOrderHole[U](args: Any*): U = ???
 
-  /** A splice of a name in a quoted pattern is that marks the definition of a type splice */
+  /** A splice of a name in a quoted pattern is that marks the definition of a type splice.
+   *
+   *  Adding this annotation in source has undefined behaviour at compile-time
+   */
   @compileTimeOnly("Illegal reference to `scala.quoted.runtime.Patterns.patternType`")
   class patternType extends Annotation
 
-  /** A type pattern that must be aproximated from above */
+  /** A type pattern that must be aproximated from above
+   *
+   *  Adding this annotation in source has undefined behaviour at compile-time
+   */
   @compileTimeOnly("Illegal reference to `scala.quoted.runtime.Patterns.fromAbove`")
   class fromAbove extends Annotation
 

library/src/scala/quoted/runtime/SplicedType.scala

@@ -9,6 +9,8 @@ import scala.annotation.{Annotation, compileTimeOnly}
  *  This artifact is removed during quote unpickling.
  *
  *  See PickleQuotes.scala and PickledQuotes.scala
+ *
+ *  Adding this annotation in source has undefined behaviour at compile-time
  */
 @compileTimeOnly("Illegal reference to `scala.quoted.runtime.SplicedType`")
 class SplicedType extends Annotation