Skip to content

Commit 98e3839

Browse files
BarkingBadBarkingBad
authored
Merge pull request #11612 from BarkingBad/scaladoc/fix-markdown-syntax
Fix markdown syntax for scala3 library docstrings
2 parents 052913d + e12edfc commit 98e3839

File tree

10 files changed

+108
-45
lines changed

10 files changed

+108
-45
lines changed

‎library/src/scala/Tuple.scala

+3-2
Original file line numberDiff line numberDiff line change
@@ -126,13 +126,14 @@ object Tuple {
126126

127127
/** Filters out those members of the tuple for which the predicate `P` returns `false`.
128128
* A predicate `P[X]` is a type that can be either `true` or `false`. For example:
129-
* ```
129+
* ```scala
130130
* type IsString[x] = x match {
131131
* case String => true
132132
* case _ => false
133133
* }
134134
* Filter[(1, "foo", 2, "bar"), IsString] =:= ("foo", "bar")
135-
* ```
135+
* ```
136+
* @syntax markdown
136137
*/
137138
type Filter[Tup <: Tuple, P[_] <: Boolean] <: Tuple = Tup match {
138139
case EmptyTuple => EmptyTuple

‎library/src/scala/compiletime/ops/any.scala

+2
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ object any:
88
* val eq2: 1 == "1" = false
99
* val eq3: "1" == "1" = true
1010
* ```
11+
* @syntax markdown
1112
*/
1213
type ==[X, Y] <: Boolean
1314

@@ -17,5 +18,6 @@ object any:
1718
* val eq2: 1 != "1" = true
1819
* val eq3: "1" != "1" = false
1920
* ```
21+
* @syntax markdown
2022
*/
2123
type !=[X, Y] <: Boolean

‎library/src/scala/compiletime/ops/boolean.scala

+12-8
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,16 @@ object boolean:
88
* val notFalse: ![false] = true
99
* val notTrue: ![true] = false
1010
* ```
11+
* @syntax markdown
1112
*/
1213
type ![X <: Boolean] <: Boolean
1314

1415
/** Exclusive disjunction of two `Boolean` singleton types.
15-
* ```scala
16-
* val a: true ^ true = false
17-
* val b: false ^ true = true
18-
* ```
16+
* ```scala
17+
* val a: true ^ true = false
18+
* val b: false ^ true = true
19+
* ```
20+
* @syntax markdown
1921
*/
2022
type ^[X <: Boolean, Y <: Boolean] <: Boolean
2123

@@ -24,13 +26,15 @@ object boolean:
2426
* val a: true && true = true
2527
* val b: false && true = false
2628
* ```
29+
* @syntax markdown
2730
*/
2831
type &&[X <: Boolean, Y <: Boolean] <: Boolean
2932

3033
/** Disjunction of two `Boolean` singleton types.
31-
* ```scala
32-
* val a: true || false = true
33-
* val b: false || false = false
34-
* ```
34+
* ```scala
35+
* val a: true || false = true
36+
* val b: false || false = false
37+
* ```
38+
* @syntax markdown
3539
*/
3640
type ||[X <: Boolean, Y <: Boolean] <: Boolean

‎library/src/scala/compiletime/ops/int.scala

+20
Original file line numberDiff line numberDiff line change
@@ -6,62 +6,71 @@ object int:
66
* ```scala
77
* val sum: 2 + 2 = 4
88
* ```
9+
* @syntax markdown
910
*/
1011
type +[X <: Int, Y <: Int] <: Int
1112

1213
/** Subtraction of two `Int` singleton types.
1314
* ```scala
1415
* val sub: 4 - 2 = 2
1516
* ```
17+
* @syntax markdown
1618
*/
1719
type -[X <: Int, Y <: Int] <: Int
1820

1921
/** Multiplication of two `Int` singleton types.
2022
* ```scala
2123
* val mul: 4 * 2 = 8
2224
* ```
25+
* @syntax markdown
2326
*/
2427
type *[X <: Int, Y <: Int] <: Int
2528

2629
/** Integer division of two `Int` singleton types.
2730
* ```scala
2831
* val div: 5 / 2 = 2
2932
* ```
33+
* @syntax markdown
3034
*/
3135
type /[X <: Int, Y <: Int] <: Int
3236

3337
/** Remainder of the division of `X` by `Y`.
3438
* ```scala
3539
* val mod: 5 % 2 = 1
3640
* ```
41+
* @syntax markdown
3742
*/
3843
type %[X <: Int, Y <: Int] <: Int
3944

4045
/** Binary left shift of `X` by `Y`.
4146
* ```scala
4247
* val lshift: 1 << 2 = 4
4348
* ```
49+
* @syntax markdown
4450
*/
4551
type <<[X <: Int, Y <: Int] <: Int
4652

4753
/** Binary right shift of `X` by `Y`.
4854
* ```scala
4955
* val rshift: 10 >> 1 = 5
5056
* ```
57+
* @syntax markdown
5158
*/
5259
type >>[X <: Int, Y <: Int] <: Int
5360

5461
/** Binary right shift of `X` by `Y`, filling the left with zeros.
5562
* ```scala
5663
* val rshiftzero: 10 >>> 1 = 5
5764
* ```
65+
* @syntax markdown
5866
*/
5967
type >>>[X <: Int, Y <: Int] <: Int
6068

6169
/** Bitwise xor of `X` and `Y`.
6270
* ```scala
6371
* val xor: 10 ^ 30 = 20
6472
* ```
73+
* @syntax markdown
6574
*/
6675
type ^[X <: Int, Y <: Int] <: Int
6776

@@ -70,6 +79,7 @@ object int:
7079
* val lt1: 4 < 2 = false
7180
* val lt2: 2 < 4 = true
7281
* ```
82+
* @syntax markdown
7383
*/
7484
type <[X <: Int, Y <: Int] <: Boolean
7585

@@ -78,6 +88,7 @@ object int:
7888
* val gt1: 4 > 2 = true
7989
* val gt2: 2 > 2 = false
8090
* ```
91+
* @syntax markdown
8192
*/
8293
type >[X <: Int, Y <: Int] <: Boolean
8394

@@ -86,6 +97,7 @@ object int:
8697
* val ge1: 4 >= 2 = true
8798
* val ge2: 2 >= 3 = false
8899
* ```
100+
* @syntax markdown
89101
*/
90102
type >=[X <: Int, Y <: Int] <: Boolean
91103

@@ -94,6 +106,7 @@ object int:
94106
* val lt1: 4 <= 2 = false
95107
* val lt2: 2 <= 2 = true
96108
* ```
109+
* @syntax markdown
97110
*/
98111
type <=[X <: Int, Y <: Int] <: Boolean
99112

@@ -102,20 +115,23 @@ object int:
102115
* val and1: BitwiseAnd[4, 4] = 4
103116
* val and2: BitwiseAnd[10, 5] = 0
104117
* ```
118+
* @syntax markdown
105119
*/
106120
type BitwiseAnd[X <: Int, Y <: Int] <: Int
107121

108122
/** Bitwise or of `X` and `Y`.
109123
* ```scala
110124
* val or: BitwiseOr[10, 11] = 11
111125
* ```
126+
* @syntax markdown
112127
*/
113128
type BitwiseOr[X <: Int, Y <: Int] <: Int
114129

115130
/** Absolute value of an `Int` singleton type.
116131
* ```scala
117132
* val abs: Abs[-1] = 1
118133
* ```
134+
* @syntax markdown
119135
*/
120136
type Abs[X <: Int] <: Int
121137

@@ -124,26 +140,30 @@ object int:
124140
* val neg1: Neg[-1] = 1
125141
* val neg2: Neg[1] = -1
126142
* ```
143+
* @syntax markdown
127144
*/
128145
type Negate[X <: Int] <: Int
129146

130147
/** Minimum of two `Int` singleton types.
131148
* ```scala
132149
* val min: Min[-1, 1] = -1
133150
* ```
151+
* @syntax markdown
134152
*/
135153
type Min[X <: Int, Y <: Int] <: Int
136154

137155
/** Maximum of two `Int` singleton types.
138156
* ```scala
139157
* val max: Max[-1, 1] = 1
140158
* ```
159+
* @syntax markdown
141160
*/
142161
type Max[X <: Int, Y <: Int] <: Int
143162

144163
/** String conversion of an `Int` singleton type.
145164
* ```scala
146165
* val abs: ToString[1] = "1"
147166
* ```
167+
* @syntax markdown
148168
*/
149169
type ToString[X <: Int] <: String

‎library/src/scala/compiletime/ops/string.scala

+1
Original file line numberDiff line numberDiff line change
@@ -6,5 +6,6 @@ object string:
66
* ```scala
77
* val hello: "hello " + "world" = "hello world"
88
* ```
9+
* @syntax markdown
910
*/
1011
type +[X <: String, Y <: String] <: String

‎library/src/scala/compiletime/package.scala

+30-19
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,15 @@ package object compiletime {
66
/** Use this method when you have a type, do not have a value for it but want to
77
* pattern match on it. For example, given a type `Tup <: Tuple`, one can
88
* pattern-match on it as follows:
9-
* ```
9+
* ```scala
1010
* inline erasedValue[Tup] match {
1111
* case _: EmptyTuple => ...
1212
* case _: h *: t => ...
1313
* }
1414
* ```
1515
* This value can only be used in an inline match and the value cannot be used in
1616
* the branches.
17+
* @syntax markdown
1718
*/
1819
erased def erasedValue[T]: T = ???
1920

@@ -39,6 +40,7 @@ package object compiletime {
3940
* inline def errorOnThisCode(inline x: Any) =
4041
* error("My error of this code: " + codeOf(x))
4142
* ```
43+
* @syntax markdown
4244
*/
4345
inline def error(inline msg: String): Nothing = ???
4446

@@ -55,8 +57,10 @@ package object compiletime {
5557
*
5658
* The formatting of the code is not stable across version of the compiler.
5759
*
58-
* @note only `inline` arguments will be displayed as "code".
59-
* Other values may display unintutively.
60+
* @note only `inline` arguments will be displayed as "code".
61+
* Other values may display unintutively.
62+
*
63+
* @syntax markdown
6064
*/
6165
transparent inline def codeOf(arg: Any): String =
6266
// implemented in dotty.tools.dotc.typer.Inliner.Intrinsics
@@ -75,6 +79,7 @@ package object compiletime {
7579
* val m: Int = ...
7680
* twice(m) // error: expected a constant value but found: m
7781
* ```
82+
* @syntax markdown
7883
*/
7984
inline def requireConst(inline x: Boolean | Byte | Short | Int | Long | Float | Double | Char | String): Unit =
8085
// implemented in dotty.tools.dotc.typer.Inliner
@@ -97,10 +102,11 @@ package object compiletime {
97102

98103
/**
99104
* Use this type to widen a self-type to a tuple. E.g.
100-
* ```
105+
* ```scala
101106
* val x: (1, 3) = (1, 3)
102107
* val y: Widen[x.type] = x
103108
* ```
109+
* @syntax markdown
104110
*/
105111
type Widen[Tup <: Tuple] <: Tuple = Tup match {
106112
case EmptyTuple => EmptyTuple
@@ -121,16 +127,18 @@ package object compiletime {
121127

122128
/** Summons first given matching one of the listed cases. E.g. in
123129
*
124-
* given B { ... }
125-
*
126-
* summonFrom {
127-
* case given A => 1
128-
* case given B => 2
129-
* case given C => 3
130-
* case _ => 4
131-
* }
130+
* ```scala
131+
* given B { ... }
132132
*
133+
* summonFrom {
134+
* case given A => 1
135+
* case given B => 2
136+
* case given C => 3
137+
* case _ => 4
138+
* }
139+
* ```
133140
* the returned value would be `2`.
141+
* @syntax markdown
134142
*/
135143
transparent inline def summonFrom[T](f: Nothing => T): T =
136144
error("Compiler bug: `summonFrom` was not evaluated by the compiler")
@@ -162,13 +170,16 @@ package object compiletime {
162170

163171
/** Succesor of a natural number where zero is the type 0 and successors are reduced as if the definition was
164172
*
165-
* type S[N <: Int] <: Int = N match {
166-
* case 0 => 1
167-
* case 1 => 2
168-
* case 2 => 3
169-
* ...
170-
* case 2147483646 => 2147483647
171-
* }
173+
* ```scala
174+
* type S[N <: Int] <: Int = N match {
175+
* case 0 => 1
176+
* case 1 => 2
177+
* case 2 => 3
178+
* ...
179+
* case 2147483646 => 2147483647
180+
* }
181+
* ```
182+
* @syntax markdown
172183
*/
173184
type S[N <: Int] <: Int
174185

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

+2-2
Original file line numberDiff line numberDiff line change
@@ -40,13 +40,14 @@ object Expr {
4040
* Otherwise returns `None`.
4141
*
4242
* Usage:
43-
* ```
43+
* ```scala
4444
* case '{ ... ${expr @ Expr(value)}: T ...} =>
4545
* // expr: Expr[T]
4646
* // value: T
4747
* ```
4848
*
4949
* To directly get the value of an expression `expr: Expr[T]` consider using `expr.value`/`expr.valueOrError` insead.
50+
* @syntax markdown
5051
*/
5152
def unapply[T](x: Expr[T])(using FromExpr[T])(using Quotes): Option[T] =
5253
scala.Predef.summon[FromExpr[T]].unapply(x)
@@ -57,7 +58,6 @@ object Expr {
5758
* `Seq(e1, e2, ...)` where `ei: Expr[T]`
5859
* to an expression equivalent to
5960
* `'{ Seq($e1, $e2, ...) }` typed as an `Expr[Seq[T]]`
60-
* ```
6161
*/
6262
def ofSeq[T](xs: Seq[Expr[T]])(using Type[T])(using Quotes): Expr[Seq[T]] =
6363
Varargs(xs)

0 commit comments

Comments
 (0)