Skip to content

Commit d192c1f

Browse files
nicolasstuckinicolasstucki
committed
Add some docs in Quotes.scala
1 parent a6e75ca commit d192c1f

File tree

2 files changed

+151
-21
lines changed

2 files changed

+151
-21
lines changed

‎compiler/src/scala/quoted/runtime/impl/QuotesImpl.scala

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,8 +153,10 @@ class QuotesImpl private (using val ctx: Context) extends Quotes, QuoteUnpickler
153153

154154
object Import extends ImportModule:
155155
def apply(expr: Term, selectors: List[Selector]): Import =
156+
if selectors.isEmpty then throw IllegalArgumentException("Empty selectors")
156157
withDefaultPos(tpd.Import(expr, selectors))
157158
def copy(original: Tree)(expr: Term, selectors: List[Selector]): Import =
159+
if selectors.isEmpty then throw IllegalArgumentException("Empty selectors")
158160
tpd.cpy.Import(original)(expr, selectors)
159161
def unapply(tree: Import): (Term, List[Selector]) =
160162
(tree.expr, tree.selectors)

‎library/src/scala/quoted/Quotes.scala

Lines changed: 149 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,15 @@
1-
package scala.quoted
2-
31
import scala.reflect.TypeTest
42

5-
/** Current Quotes in scope */
3+
/** Current Quotes in scope
4+
*
5+
* Usage:
6+
* ```scala
7+
* def myExpr[T](using Quotes): Expr[T] = {
8+
* import quotes.relect._
9+
* ...
10+
* }
11+
* ```
12+
*/
613
inline def quotes(using q: Quotes): q.type = q
714

815
/** Quotation context provided by a macro expansion or in the scope of `scala.quoted.staging.run`.
@@ -223,8 +230,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
223230
val Tree: TreeModule
224231

225232
/** Methods of the module object `val Tree` */
226-
trait TreeModule { this: Tree.type =>
227-
}
233+
trait TreeModule { this: Tree.type => }
228234

229235
/** Makes extension methods on `Tree` available without any imports */
230236
given TreeMethods: TreeMethods
@@ -260,7 +266,21 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
260266

261267
}
262268

263-
/** Tree representing a pacakage clause in the source code */
269+
/** Tree representing a pacakage clause in the source code
270+
*
271+
* ```scala
272+
* package foo {
273+
* // package stats
274+
* }
275+
* ```
276+
*
277+
* or
278+
*
279+
* ```scala
280+
* package foo.bar
281+
* // package stats
282+
* ```
283+
*/
264284
type PackageClause <: Tree
265285

266286
/** `TypeTest` that allows testing at runtime in a pattern match if a `Tree` is a `PackageClause` */
@@ -271,8 +291,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
271291

272292
/** Methods of the module object `val PackageClause` */
273293
trait PackageClauseModule { this: PackageClause.type =>
294+
/** Create a package clause `package pid { stats }` */
274295
def apply(pid: Ref, stats: List[Tree]): PackageClause
296+
/** Copy a package clause `package pid { stats }` */
275297
def copy(original: Tree)(pid: Ref, stats: List[Tree]): PackageClause
298+
/** Matches a package clause `package pid { stats }` and extracts the `pid` and `stats` */
276299
def unapply(tree: PackageClause): (Ref, List[Tree])
277300
}
278301

@@ -282,12 +305,17 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
282305
/** Extension methods of `PackageClause` */
283306
trait PackageClauseMethods:
284307
extension (self: PackageClause)
308+
/** Tree containing the package name */
285309
def pid: Ref
310+
/** Definitions, imports or exports within the package */
286311
def stats: List[Tree]
287312
end extension
288313
end PackageClauseMethods
289314

290-
/** Tree representing an import in the source code */
315+
/** Tree representing an import in the source code.
316+
*
317+
* See also documentation on `Selector`.
318+
*/
291319
type Import <: Statement
292320

293321
/** `TypeTest` that allows testing at runtime in a pattern match if a `Tree` is an `Import` */
@@ -298,8 +326,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
298326

299327
/** Methods of the module object `val Import` */
300328
trait ImportModule { this: Import.type =>
329+
/** Create an `Import` with the given qualifier and selectors */
301330
def apply(expr: Term, selectors: List[Selector]): Import
331+
/** Copy an `Import` with the given qualifier and selectors */
302332
def copy(original: Tree)(expr: Term, selectors: List[Selector]): Import
333+
/** Matches an `Import` and extracts the qualifier and selectors */
303334
def unapply(tree: Import): (Term, List[Selector])
304335
}
305336

@@ -309,7 +340,12 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
309340
/** Extension methods of `Import` */
310341
trait ImportMethods:
311342
extension (self: Import)
343+
/** Qualifier of the import */
312344
def expr: Term
345+
/** List Selectors of the import
346+
*
347+
* See documentation on `Selector`
348+
*/
313349
def selectors: List[Selector]
314350
end extension
315351
end ImportMethods
@@ -327,6 +363,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
327363

328364
/** Methods of the module object `val Export` */
329365
trait ExportModule { this: Export.type =>
366+
/** Matches an `Export` and extracts the qualifier and selectors */
330367
def unapply(tree: Export): (Term, List[Selector])
331368
}
332369

@@ -336,7 +373,12 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
336373
/** Extension methods of `Export` */
337374
trait ExportMethods:
338375
extension (self: Export)
376+
/** Qualifier of the export */
339377
def expr: Term
378+
/** List Selectors of the export
379+
*
380+
* See documentation on `Selector`
381+
*/
340382
def selectors: List[Selector]
341383
end extension
342384
end ExportMethods
@@ -367,6 +409,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
367409
/** Extension methods of `Definition` */
368410
trait DefinitionMethods:
369411
extension (self: Definition)
412+
/** Name of the definition */
370413
def name: String
371414
end extension
372415
end DefinitionMethods
@@ -395,10 +438,31 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
395438
/** Extension methods of `ClassDef` */
396439
trait ClassDefMethods:
397440
extension (self: ClassDef)
441+
/** The primary constructor of this class */
398442
def constructor: DefDef
443+
/** List of extended parent classes or traits.
444+
* The first parent is always a class.
445+
*/
399446
def parents: List[Tree /* Term | TypeTree */]
400-
def derived: List[TypeTree]
447+
/** List of derived type classes */
448+
def derived: List[TypeTree] // TODO remove? It seems these don't exist after desugaring
449+
/** Self-type of the class
450+
*
451+
* ```scala
452+
* class C { self: T =>
453+
* ...
454+
* }
455+
* ```
456+
*/
401457
def self: Option[ValDef]
458+
/** Statements within the class
459+
*
460+
* ```scala
461+
* class C {
462+
* ... // statemets
463+
* }
464+
* ```
465+
*/
402466
def body: List[Statement]
403467
end extension
404468
end ClassDefMethods
@@ -452,7 +516,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
452516
/** List of term parameter clauses */
453517
def termParamss: List[TermParamClause]
454518

455-
/** The tree of the return type of the method */
519+
/** The tree of the return type of this `def` definition */
456520
def returnTpt: TypeTree
457521

458522
/** The tree of the implementation of the method.
@@ -496,7 +560,9 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
496560
/** Extension methods of `ValDef` */
497561
trait ValDefMethods:
498562
extension (self: ValDef)
563+
/** The type tree of this `val` definition */
499564
def tpt: TypeTree
565+
/** The right-hand side of this `val` definition */
500566
def rhs: Option[Term]
501567
end extension
502568
end ValDefMethods
@@ -515,8 +581,8 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
515581
/** Methods of the module object `val TypeDef` */
516582
trait TypeDefModule { this: TypeDef.type =>
517583
def apply(symbol: Symbol): TypeDef
518-
def copy(original: Tree)(name: String, rhs: Tree /*TypeTree | TypeBoundsTree*/): TypeDef
519-
def unapply(tdef: TypeDef): (String, Tree /*TypeTree | TypeBoundsTree*/ /* TypeTree | TypeBoundsTree */)
584+
def copy(original: Tree)(name: String, rhs: Tree): TypeDef
585+
def unapply(tdef: TypeDef): (String, Tree)
520586
}
521587

522588
/** Makes extension methods on `TypeDef` available without any imports */
@@ -525,7 +591,8 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
525591
/** Extension methods of `TypeDef` */
526592
trait TypeDefMethods:
527593
extension (self: TypeDef)
528-
def rhs: Tree /*TypeTree | TypeBoundsTree*/
594+
/** The type bounds on the right-hand side of this `type` definition */
595+
def rhs: Tree
529596
end extension
530597
end TypeDefMethods
531598

@@ -666,6 +733,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
666733
/** Extension methods of `Ident` */
667734
trait IdentMethods:
668735
extension (self: Ident)
736+
/** Name of this `Ident` */
669737
def name: String
670738
end extension
671739
end IdentMethods
@@ -710,8 +778,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
710778
/** Extension methods of `Select` */
711779
trait SelectMethods:
712780
extension (self: Select)
781+
/** Qualifier of the `qualifier.name` */
713782
def qualifier: Term
783+
/** Name of this `Select` */
714784
def name: String
785+
/** Signature of this method */
715786
def signature: Option[Signature]
716787
end extension
717788
end SelectMethods
@@ -743,11 +814,12 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
743814
/** Extension methods of `Literal` */
744815
trait LiteralMethods:
745816
extension (self: Literal)
817+
/** Value of this literal */
746818
def constant: Constant
747819
end extension
748820
end LiteralMethods
749821

750-
/** Tree representing `this` in the source code */
822+
/** Tree representing `this` or `C.this` in the source code */
751823
type This <: Term
752824

753825
/** `TypeTest` that allows testing at runtime in a pattern match if a `Tree` is a `This` */
@@ -759,12 +831,12 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
759831
/** Methods of the module object `val This` */
760832
trait ThisModule { this: This.type =>
761833

762-
/** Create a `this[<id: String]>` */
834+
/** Create a `C.this` for `C` pointing to `cls` */
763835
def apply(cls: Symbol): This
764836

765837
def copy(original: Tree)(qual: Option[String]): This
766838

767-
/** Matches `this[<id: Option[String]>` */
839+
/** Matches `this` or `qual.this` and returns the name of `qual` */
768840
def unapply(x: This): Some[Option[String]]
769841
}
770842

@@ -774,6 +846,10 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
774846
/** Extension methods of `This` */
775847
trait ThisMethods:
776848
extension (self: This)
849+
/** Returns `C` if the underlying tree is of the form `C.this`
850+
*
851+
* Otherwise, return `None`.
852+
*/
777853
def id: Option[String]
778854
end extension
779855
end ThisMethods
@@ -795,7 +871,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
795871

796872
def copy(original: Tree)(tpt: TypeTree): New
797873

798-
/** Matches a `new <tpt: TypeTree>` */
874+
/** Matches `new <tpt: TypeTree>` */
799875
def unapply(x: New): Some[TypeTree]
800876
}
801877

@@ -805,6 +881,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
805881
/** Extension methods of `New` */
806882
trait NewMethods:
807883
extension (self: New)
884+
/** Returns the type tree of this `new` */
808885
def tpt: TypeTree
809886
end extension
810887
end NewMethods
@@ -836,7 +913,9 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
836913
/** Extension methods of `NamedArg` */
837914
trait NamedArgMethods:
838915
extension (self: NamedArg)
916+
/** The name part of `name = arg` */
839917
def name: String
918+
/** The argument part of `name = arg` */
840919
def value: Term
841920
end extension
842921
end NamedArgMethods
@@ -868,7 +947,27 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
868947
/** Extension methods of `Apply` */
869948
trait ApplyMethods:
870949
extension (self: Apply)
950+
/** The `fun` part of an (implicit) application like `fun(args)`
951+
*
952+
* It maybe a partially applied method:
953+
* ```scala
954+
* def f(x1: Int)(x2: Int) = ...
955+
* f(1)(2)
956+
* ```
957+
* - `fun` is `f(1)` in the `Apply` of `f(1)(2)`
958+
* - `fun` is `f` in the `Apply` of `f(1)`
959+
*/
871960
def fun: Term
961+
/** The arguments (implicitly) passed to the method
962+
*
963+
* The `Apply` maybe a partially applied method:
964+
* ```scala
965+
* def f(x1: Int)(x2: Int) = ...
966+
* f(1)(2)
967+
* ```
968+
* - `args` is `(2)` in the `Apply` of `f(1)(2)`
969+
* - `args` is `(1)` in the `Apply` of `f(1)`
970+
*/
872971
def args: List[Term]
873972
end extension
874973
end ApplyMethods
@@ -900,7 +999,35 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
900999
/** Extension methods of `TypeApply` */
9011000
trait TypeApplyMethods:
9021001
extension (self: TypeApply)
1002+
/** The `fun` part of an (inferred) type application like `fun[Args]`
1003+
*
1004+
* It maybe a partially applied method:
1005+
* ```scala
1006+
* extension (x: Int) def f[T](y: T) = ...
1007+
* // represented as
1008+
* // def f(x: Int)[T](y: T) = ...
1009+
*
1010+
* 1.f[Int](2)
1011+
* // represented as
1012+
* // f(1)[Int](2)
1013+
* ```
1014+
* - `fun` is `f(1)` in the `TypeApply` of `f(1)[Int]`
1015+
*/
9031016
def fun: Term
1017+
/** The (inferred) type arguments passed to the method
1018+
*
1019+
* The `TypeApply` maybe a partially applied method:
1020+
* ```scala
1021+
* extension (x: Int) def f[T](y: T) = ...
1022+
* // represented as
1023+
* // def f(x: Int)[T](y: T) = ...
1024+
*
1025+
* 1.f[Int](2)
1026+
* // represented as
1027+
* // f(1)[Int](2)
1028+
* ```
1029+
* - `fun` is `[Int]` in the `TypeApply` of `f(1)[Int]`
1030+
*/
9041031
def args: List[TypeTree]
9051032
end extension
9061033
end TypeApplyMethods
@@ -2040,11 +2167,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
20402167
/////////////////////
20412168

20422169
/** Import/Export selectors:
2043-
* * SimpleSelector: `.bar` in `import foo.bar`
2044-
* * RenameSelector: `.{bar => baz}` in `export foo.{bar => baz}`
2045-
* * OmitSelector: `.{bar => _}` in `import foo.{bar => _}`
2046-
* * GivenSelector: `.given`/`.{given T}` in `export foo.given`/`import foo.{given T}`
2047-
*/
2170+
* - SimpleSelector: `.bar` in `import foo.bar`
2171+
* - RenameSelector: `.{bar => baz}` in `export foo.{bar => baz}`
2172+
* - OmitSelector: `.{bar => _}` in `import foo.{bar => _}`
2173+
* - GivenSelector: `.given`/`.{given T}` in `export foo.given`/`import foo.{given T}`
2174+
*/
20482175
type Selector <: AnyRef
20492176

20502177
/** Module object of `type Selector` */
@@ -4324,3 +4451,4 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
43244451
type Nested = Quotes
43254452

43264453
}
4454+

0 commit comments

Comments
 (0)