Skip to content

Commit a86c97a

Browse files
pikinier20pikinier20
authored
Merge pull request #13521 from KacperFKorban/scaladoc/fix-quoted-snippets
Setup snippet compiler for scala.quoted and fix snippets
2 parents a0875e2 + 78b48bc commit a86c97a

File tree

6 files changed

+96
-40
lines changed

6 files changed

+96
-40
lines changed

‎library/src/scala/quoted/Expr.scala

+1-1
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ object Expr {
4040
* Otherwise returns `None`.
4141
*
4242
* Usage:
43-
* ```scala
43+
* ```scala sc:nocompile
4444
* case '{ ... ${expr @ Expr(value)}: T ...} =>
4545
* // expr: Expr[T]
4646
* // value: T

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

+54-30
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import scala.reflect.TypeTest
66
/** Current Quotes in scope
77
*
88
* Usage:
9-
* ```scala
9+
* ```scala sc:nocompile
1010
* def myExpr[T](using Quotes): Expr[T] = {
1111
* import quotes.reflect._
1212
* ...
@@ -31,7 +31,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
3131

3232
/** Pattern matches `this` against `that`. Effectively performing a deep equality check.
3333
* It does the equivalent of
34-
* ```scala
34+
* ```scala sc:nocompile
3535
* this match
3636
* case '{...} => true // where the contents of the pattern are the contents of `that`
3737
* case _ => false
@@ -91,7 +91,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
9191
* def f(expr: Expr[Int])(using Quotes) =
9292
* import quotes.reflect._
9393
* val ast: Term = expr.asTerm
94-
* ...
94+
* ???
9595
* ```
9696
*
9797
* See `reflectModule` for full API.
@@ -294,15 +294,15 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
294294

295295
/** Tree representing a package clause in the source code
296296
*
297-
* ```scala
297+
* ```scala sc:nocompile
298298
* package foo {
299-
* // package stats
299+
* // package stats
300300
* }
301301
* ```
302302
*
303303
* or
304304
*
305-
* ```scala
305+
* ```scala sc:nocompile
306306
* package foo.bar
307307
* // package stats
308308
* ```
@@ -473,8 +473,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
473473
/** Self-type of the class
474474
*
475475
* ```scala
476+
* //{
477+
* type T
478+
* //}
476479
* class C { self: T =>
477-
* ...
480+
* ???
478481
* }
479482
* ```
480483
* @syntax markdown
@@ -484,7 +487,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
484487
*
485488
* ```scala
486489
* class C {
487-
* ... // statements
490+
* ??? // statements
488491
* }
489492
* ```
490493
* @syntax markdown
@@ -532,7 +535,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
532535
*
533536
* Note: Non leading type parameters can be found in extension methods such as
534537
* ```scala
535-
* extension (a: A) def f[T]() = ...
538+
* //{
539+
* type A
540+
* type T
541+
* //}
542+
* extension (a: A) def f[T]() = ???
536543
* ```
537544
* @syntax markdown
538545
*/
@@ -543,7 +550,11 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
543550
*
544551
* Non leading type parameters can be found in extension methods such as
545552
* ```scala
546-
* extension (a: A) def f[T]() = ...
553+
* //{
554+
* type T
555+
* type A
556+
* //}
557+
* extension (a: A) def f[T]() = ???
547558
* ```
548559
* @syntax markdown
549560
*/
@@ -1014,7 +1025,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
10141025
*
10151026
* It may be a partially applied method:
10161027
* ```scala
1017-
* def f(x1: Int)(x2: Int) = ...
1028+
* def f(x1: Int)(x2: Int) = ???
10181029
* f(1)(2)
10191030
* ```
10201031
* - `fun` is `f(1)` in the `Apply` of `f(1)(2)`
@@ -1026,7 +1037,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
10261037
*
10271038
* The `Apply` may be a partially applied method:
10281039
* ```scala
1029-
* def f(x1: Int)(x2: Int) = ...
1040+
* def f(x1: Int)(x2: Int) = ???
10301041
* f(1)(2)
10311042
* ```
10321043
* - `args` is `(2)` in the `Apply` of `f(1)(2)`
@@ -1068,9 +1079,12 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
10681079
*
10691080
* It may be a partially applied method:
10701081
* ```scala
1071-
* extension (x: Int) def f[T](y: T) = ...
1082+
* //{
1083+
* type T
1084+
* //}
1085+
* extension (x: Int) def f[T](y: T) = ???
10721086
* // represented as
1073-
* // def f(x: Int)[T](y: T) = ...
1087+
* // def f(x: Int)[T](y: T) = ???
10741088
*
10751089
* 1.f[Int](2)
10761090
* // represented as
@@ -1084,9 +1098,12 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
10841098
*
10851099
* The `TypeApply` may be a partially applied method:
10861100
* ```scala
1087-
* extension (x: Int) def f[T](y: T) = ...
1101+
* //{
1102+
* type T
1103+
* //}
1104+
* extension (x: Int) def f[T](y: T) = ???
10881105
* // represented as
1089-
* // def f(x: Int)[T](y: T) = ...
1106+
* // def f(x: Int)[T](y: T) = ???
10901107
*
10911108
* 1.f[Int](2)
10921109
* // represented as
@@ -1273,7 +1290,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
12731290
/** A lambda `(...) => ...` in the source code is represented as
12741291
* a local method and a closure:
12751292
*
1276-
* ```scala
1293+
* ```scala sc:nocompile
12771294
* {
12781295
* def m(...) = ...
12791296
* closure(m)
@@ -1289,7 +1306,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
12891306
/** Methods of the module object `val Lambda` */
12901307
trait LambdaModule { this: Lambda.type =>
12911308
/** Matches a lambda definition of the form
1292-
* ```scala
1309+
* ```scala sc:nocompile
12931310
* Block((DefDef(_, _, params :: Nil, _, Some(body))) :: Nil, Closure(meth, _))
12941311
* ```
12951312
* Extracts the parameter definitions and body.
@@ -1298,7 +1315,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
12981315
def unapply(tree: Block): Option[(List[ValDef], Term)]
12991316

13001317
/** Generates a lambda with the given method type.
1301-
* ```scala
1318+
* ```scala sc:nocompile
13021319
* Block((DefDef(_, _, params :: Nil, _, Some(rhsFn(meth, paramRefs)))) :: Nil, Closure(meth, _))
13031320
* ```
13041321
* @param owner: owner of the generated `meth` symbol
@@ -2432,9 +2449,16 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
24322449
*
24332450
* Usage:
24342451
* ```scala
2452+
* //{
2453+
* def f(using Quotes) = {
2454+
* val typeRepr: TypeRepr = ???
2455+
* //}
24352456
* typeRepr.asType match
24362457
* case '[t] =>
2437-
* '{ val x: t = ... }
2458+
* '{ val x: t = ??? }
2459+
* //{
2460+
* }
2461+
* //}
24382462
* ```
24392463
* @syntax markdown
24402464
*/
@@ -2809,12 +2833,15 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
28092833
*
28102834
* May represent by-name parameter such as `thunk` in
28112835
* ```scala
2812-
* def log[T](thunk: =>T): T = ...
2836+
* //{
2837+
* type T
2838+
* //}
2839+
* def log[T](thunk: => T): T = ???
28132840
* ```
28142841
*
28152842
* May also represent a the return type of a parameterless method definition such as
28162843
* ```scala
2817-
* def foo: Int = ...
2844+
* def foo: Int = ???
28182845
* ```
28192846
* @syntax markdown
28202847
*/
@@ -3451,7 +3478,7 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
34513478
/** Symbol of the definition that encloses the current splicing context.
34523479
*
34533480
* For example, the following call to `spliceOwner` would return the symbol `x`.
3454-
* ```scala
3481+
* ```scala sc:nocompile
34553482
* val x = ${ ... Symbol.spliceOwner ... }
34563483
* ```
34573484
*
@@ -4298,9 +4325,8 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
42984325
*
42994326
* Usage:
43004327
* ```scala
4301-
* import quotes.reflect._
4302-
* class MyTreeAccumulator extends TreeAccumulator[X] {
4303-
* def foldTree(x: X, tree: Tree)(owner: Symbol): X = ...
4328+
* class MyTreeAccumulator[X] extends TreeAccumulator[X] {
4329+
* def foldTree(x: X, tree: Tree)(owner: Symbol): X = ???
43044330
* }
43054331
* ```
43064332
* @syntax markdown
@@ -4402,9 +4428,8 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
44024428
*
44034429
* Usage:
44044430
* ```scala
4405-
* import quotes.reflect._
44064431
* class MyTraverser extends TreeTraverser {
4407-
* override def traverseTree(tree: Tree)(owner: Symbol): Unit = ...
4432+
* override def traverseTree(tree: Tree)(owner: Symbol): Unit = ???
44084433
* }
44094434
* ```
44104435
* @syntax markdown
@@ -4423,9 +4448,8 @@ trait Quotes { self: runtime.QuoteUnpickler & runtime.QuoteMatching =>
44234448
*
44244449
* Usage:
44254450
* ```scala
4426-
* import quotes.reflect._
44274451
* class MyTreeMap extends TreeMap {
4428-
* override def transformTree(tree: Tree)(owner: Symbol): Tree = ...
4452+
* override def transformTree(tree: Tree)(owner: Symbol): Tree = ???
44294453
* }
44304454
* ```
44314455
* @syntax markdown

‎library/src/scala/quoted/Type.scala

+21-3
Original file line numberDiff line numberDiff line change
@@ -27,10 +27,19 @@ object Type:
2727
*
2828
* Example usage:
2929
* ```scala
30-
* ... match
30+
* //{
31+
* import scala.deriving.*
32+
* def f(using Quotes) = {
33+
* import quotes.reflect.*
34+
* val expr: Expr[Any] = ???
35+
* //}
36+
* expr match {
3137
* case '{ $mirrorExpr : Mirror.Sum { type MirroredLabel = label } } =>
3238
* Type.valueOfConstant[label] // Option[String]
3339
* }
40+
* //{
41+
* }
42+
* //}
3443
* ```
3544
* @syntax markdown
3645
*/
@@ -43,10 +52,19 @@ object Type:
4352
*
4453
* Example usage:
4554
* ```scala
46-
* ... match
47-
* case '{ $mirrorExpr : Mirror.Sum { type MirroredElemLabels = label } } =>
55+
* //{
56+
* import scala.deriving.*
57+
* def f(using Quotes) = {
58+
* import quotes.reflect.*
59+
* val expr: Expr[Any] = ???
60+
* //}
61+
* expr match {
62+
* case '{ type label <: Tuple; $mirrorExpr : Mirror.Sum { type MirroredElemLabels = `label` } } =>
4863
* Type.valueOfTuple[label] // Option[Tuple]
4964
* }
65+
* //{
66+
* }
67+
* //}
5068
* ```
5169
* @syntax markdown
5270
*/

‎library/src/scala/quoted/Varargs.scala

+17-4
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ package scala.quoted
77
*/
88
object Varargs {
99

10-
/** Lifts this sequence of expressions into an expression of a sequence
10+
/**
11+
* Lifts this sequence of expressions into an expression of a sequence
1112
*
1213
* Transforms a sequence of expression
1314
* `Seq(e1, e2, ...)` where `ei: Expr[T]`
@@ -16,7 +17,14 @@ object Varargs {
1617
*
1718
* Usage:
1819
* ```scala
19-
* '{ List(${Varargs(List(1, 2, 3))}: _*) } // equivalent to '{ List(1, 2, 3) }
20+
* //{
21+
* def f(using Quotes) = {
22+
* import quotes.reflect.*
23+
* //}
24+
* '{ List(${Varargs(List('{1}, '{2}, '{3}))}: _*) } // equivalent to '{ List(1, 2, 3) }
25+
* //{
26+
* }
27+
* //}
2028
* ```
2129
* @syntax markdown
2230
*/
@@ -28,13 +36,18 @@ object Varargs {
2836
/** Matches a literal sequence of expressions and return a sequence of expressions.
2937
*
3038
* Usage:
31-
* ```scala
39+
* ```scala sc:nocompile
40+
* //{
41+
* object O {
42+
* //}
3243
* inline def sum(args: Int*): Int = ${ sumExpr('args) }
3344
* def sumExpr(argsExpr: Expr[Seq[Int]])(using Quotes): Expr[Int] = argsExpr match
3445
* case Varargs(argVarargs) =>
3546
* // argVarargs: Seq[Expr[Int]]
36-
* ...
47+
* ???
48+
* //{
3749
* }
50+
* //}
3851
* ```
3952
* @syntax markdown
4053
*/

‎project/Build.scala

+2-1
Original file line numberDiff line numberDiff line change
@@ -1417,7 +1417,8 @@ object Build {
14171417
"-doc-root-content", docRootFile.toString,
14181418
"-versions-dictionary-url",
14191419
"https://scala-lang.org/api/versions.json",
1420-
"-Ydocument-synthetic-types"
1420+
"-Ydocument-synthetic-types",
1421+
s"-snippet-compiler:${dottyLibRoot}/scala/quoted=compile"
14211422
) ++ (if (justAPI) Nil else Seq("-siteroot", "docs", "-Yapi-subdirectory")))
14221423

14231424
if (dottyJars.isEmpty) Def.task { streams.value.log.error("Dotty lib wasn't found") }

‎scaladoc/src/dotty/tools/scaladoc/PathBased.scala

+1-1
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ case class PathBased[T](entries: List[PathBased.Entry[T]], projectRoot: Path):
77
if path.isAbsolute then
88
if path.startsWith(projectRoot) then get(projectRoot.relativize(path))
99
else None
10-
else entries.find(_.path.forall(p => path.startsWith(p))).map(entry =>
10+
else entries.filter(_.path.forall(p => path.startsWith(p))).maxByOption(_.path.map(_.toString.length)).map(entry =>
1111
PathBased.Result(entry.path.fold(path)(_.relativize(path)), entry.elem)
1212
)
1313

0 commit comments

Comments
 (0)