Merge pull request #10669 from dotty-staging/add-some-docs

Add/update some docs in scala.quoted

Author: nicolasstucki

library/src-bootstrapped/scala/quoted/Expr.scala

@@ -1,8 +1,12 @@
 package scala.quoted
 
-/** Quoted expression of type `T` */
+/** Quoted expression of type `T`.
+ *
+ *  `Expr` has extension methods that are defined in `scala.quoted.Quotes`.
+ */
 abstract class Expr[+T] private[scala]
 
+/** Constructors for expressions */
 object Expr {
 
   /** `e.betaReduce` returns an expression that is functionally equivalent to `e`,

library/src-bootstrapped/scala/quoted/FromExpr.scala

@@ -21,6 +21,7 @@ trait FromExpr[T] {
 
 }
 
+/** Default given instances of `FromExpr` */
 object FromExpr {
 
   /** Default implementation of `FromExpr[Boolean]`

library/src-bootstrapped/scala/quoted/ToExpr.scala

@@ -12,6 +12,7 @@ trait ToExpr[T] {
 
 }
 
+/** Default given instances of `ToExpr` */
 object ToExpr {
 
   // IMPORTANT Keep in sync with tests/run-staging/liftables.scala

library/src/scala/quoted/Quotes.scala

@@ -5,7 +5,7 @@ import scala.reflect.TypeTest
 /** Current Quotes in scope */
 inline def quotes(using q: Quotes): q.type = q
 
-/** Quotation context provided by a macro expansion or in the scope of `scala.quoted.run`.
+/** Quotation context provided by a macro expansion or in the scope of `scala.quoted.staging.run`.
  *  Used to perform all operations on quoted `Expr` or `Type`.
  *
  *  It contains the low-level Typed AST API metaprogramming API.

library/src/scala/quoted/Type.scala

@@ -2,13 +2,13 @@ package scala.quoted
 
 import scala.annotation.compileTimeOnly
 
-/** Quoted type (or kind) `T` */
+/** Type (or type constructor) `T` needed contextually when using `T` in a quoted expression `'{... T ...}` */
 abstract class Type[T <: AnyKind] private[scala]:
   /** The type represented `Type` */
   type Underlying = T
 end Type
 
-/** Some basic type tags, currently incomplete */
+/** Methods to interact with the current `Type[T]` in scope */
 object Type:
 
   /** Show a source code like representation of this type without syntax highlight */

library/src/scala/quoted/Varargs.scala

@@ -1,6 +1,10 @@
 package scala.quoted
 
-/** Literal sequence of expressions */
+/** Expression reepresentation of literal sequence of expressions.
+ *
+ *  `Varargs` can be used to create the an expression `args` that will be used as varargs `'{ f($args: _*) }`
+ *  or it can be used to extract all the arguments of the a varargs.
+ */
 object Varargs {
 
   /** Lifts this sequence of expressions into an expression of a sequence