Add compiletime ops documentation

+ Add test to check that code example in the documentation compiles

Author: MaximeKjaer

docs/docs/reference/metaprogramming/inline.md

@@ -295,7 +295,7 @@ val intTwo: 2 = natTwo
 
 The `scala.compiletime` package contains helper definitions that provide support for compile time operations over values. They are described in the following.
 
-#### `constValue`, `constValueOpt`, and the `S` combinator
+### `constValue`, `constValueOpt`, and the `S` combinator
 
 `constvalue` is a function that produces the constant value represented by a
 type.
@@ -317,7 +317,7 @@ enabling us to handle situations where a value is not present. Note that `S` is
 the type of the successor of some singleton type. For example the type `S[1]` is
 the singleton type `2`.
 
-#### `erasedValue`
+### `erasedValue`
 
 So far we have seen inline methods that take terms (tuples and integers) as
 parameters. What if we want to base case distinctions on types instead? For
@@ -381,7 +381,7 @@ final val two = toIntT[Succ[Succ[Zero.type]]]
 behavior. Since `toInt` performs static checks over the static type of `N` we
 can safely use it to scrutinize its return type (`S[S[Z]]` in this case).
 
-#### `error`
+### `error`
 
 The `error` method is used to produce user-defined compile errors during inline expansion.
 It has the following signature:
@@ -411,6 +411,54 @@ inline def fail(p1: => Any) = {
 fail(identity("foo")) // error: failed on: identity("foo")
 ```
 
+### The `scala.compiletime.ops` package
+
+The `scala.compiletime.ops` package contains types that provide support for
+primitive operations on singleton types. For example, 
+`scala.compiletime.ops.int.*` provides support for multiplying two singleton
+`Int` types, and `scala.compiletime.ops.boolean.&&` for the conjunction of two
+`Boolean` types. When all arguments to a type in `scala.compiletime.ops` are
+singleton types, the compiler can evaluate the result of the operation.
+
+```scala
+import scala.compiletime.ops.int._
+import scala.compiletime.ops.boolean._
+
+val conjunction: true && true = true
+val multiplication: 3 * 5 = 15 
+```
+
+Many of these singleton operation types are meant to be used infix (as in [SLS §
+3.2.8](https://www.scala-lang.org/files/archive/spec/2.12/03-types.html#infix-types)),
+and are annotated with [`@infix`](scala.annotation.infix) accordingly.
+
+Since type aliases have the same precedence rules as their term-level 
+equivalents, the operations compose with the expected precedence rules:
+
+```scala
+import scala.compiletime.ops.int._
+val x: 1 + 2 * 3 = 7
+```
+
+The operation types are located in packages named after the type of the 
+left-hand side parameter: for instance, `scala.compiletime.int.+` represents
+addition of two numbers, while `scala.compiletime.string.+` represents string
+concatenation. To use both and distinguish the two types from each other, a 
+match type can dispatch to the correct implementation:
+
+```scala
+import scala.compiletime.ops._
+import scala.annotation.infix
+
+@infix type +[X <: Int | String, Y <: Int | String] = (X, Y) match {
+  case (Int, Int) => int.+[X, Y]
+  case (String, String) => string.+[X, Y]
+}
+
+val concat: "a" + "b" = "ab"
+val addition: 1 + 1 = 2
+```
+
 ## Summoning Implicits Selectively
 
 It is foreseen that many areas of typelevel programming can be done with rewrite

library/src/scala/compiletime/ops/package.scala

@@ -3,36 +3,170 @@ package scala.compiletime
 import scala.annotation.infix
 
 package object ops {
+  /** Equality comparison of two singleton types.
+   *  ```scala
+   *  val eq1: 1 == 1 = true
+   *  val eq2: 1 == "1" = false
+   *  val eq3: "1" == "1" = true
+   *  ```
+   */
   @infix type ==[X <: AnyVal, Y <: AnyVal] <: Boolean
+
+  /** Inequality comparison of two singleton types.
+   *  ```scala
+   *  val eq1: 1 != 1 = false
+   *  val eq2: 1 != "1" = true
+   *  val eq3: "1" != "1" = false
+   *  ```
+   */
   @infix type !=[X <: AnyVal, Y <: AnyVal] <: Boolean
 
   object string {
+    /** Concatenation of two `String` singleton types.
+     *  ```scala
+     *  val hello: "hello " + "world" = "hello world"
+     *  ```
+     */
     @infix type +[X <: String, Y <: String] <: String
   }
 
   object int {
+    /** Addition of two `Int` singleton types. Type-level equivalent of `scala.Int.+`
+     *  ```scala
+     *  val sum: 2 + 2 = 4
+     *  ```
+     */
     @infix type +[X <: Int, Y <: Int] <: Int
+
+    /** Subtraction of two `Int` singleton types. Type-level equivalent of `scala.Int.-`
+     *  ```scala
+     *  val sub: 4 - 2 = 2
+     *  ```
+     */
     @infix type -[X <: Int, Y <: Int] <: Int
+
+    /** Multiplication of two `Int` singleton types. Type-level equivalent of `scala.Int.*`
+     *  ```scala
+     *  val mul: 4 * 2 = 8
+     *  ```
+     */
     @infix type *[X <: Int, Y <: Int] <: Int
+
+    /** Integer division of two `Int` singleton types. Type-level equivalent of `scala.Int./`
+     *  ```scala
+     *  val div: 5 / 2 = 2
+     *  ```
+     */
     @infix type /[X <: Int, Y <: Int] <: Int
+
+    /** Remainder of the division of `X` by `Y`. Type-level equivalent of `scala.Int.%`
+     *  ```scala
+     *  val mod: 5 % 2 = 1
+     *  ```
+     */
     @infix type %[X <: Int, Y <: Int] <: Int
 
+    /** Less-than comparison of two `Int` singleton types. Type-level equivalent of `scala.Int.<`.
+     *  ```scala
+     *  val lt1: 4 < 2 = false
+     *  val lt2: 2 < 4 = true
+     *  ```
+     */
     @infix type <[X <: Int, Y <: Int] <: Boolean
+
+    /** Greater-than comparison of two `Int` singleton types. Type-level equivalent of `scala.Int.>`.
+     *  ```scala
+     *  val gt1: 4 > 2 = true
+     *  val gt2: 2 > 2 = false
+     *  ```
+     */
     @infix type >[X <: Int, Y <: Int] <: Boolean
+
+    /** Greater-or-equal comparison of two `Int` singleton types. Type-level equivalent of `scala.Int.>=`.
+     *  ```scala
+     *  val ge1: 4 >= 2 = true
+     *  val ge2: 2 >= 3 = false
+     *  ```
+     */
     @infix type >=[X <: Int, Y <: Int] <: Boolean
+
+    /** Less-or-equal comparison of two `Int` singleton types. Type-level equivalent of `scala.Int.<=`.
+     *  ```scala
+     *  val lt1: 4 <= 2 = false
+     *  val lt2: 2 <= 2 = true
+     *  ```
+     */
     @infix type <=[X <: Int, Y <: Int] <: Boolean
 
+    /** Absolute value of an `Int` singleton type. Type-level equivalent of `scala.Int.abs`.
+     *  ```scala
+     *  val abs: Abs[-1] = 1
+     *  ```
+     */
     type Abs[X <: Int] <: Int
+
+    /** Negation of an `Int` singleton type. Type-level equivalent of `scala.Int.unary_-`.
+     *  ```scala
+     *  val neg1: Neg[-1] = 1
+     *  val neg2: Neg[1] = -1
+     *  ```
+     */
     type Negate[X <: Int] <: Int
+
+    /** Minimum of two `Int` singleton types. Type-level equivalent of `scala.Int.min`.
+     *  ```scala
+     *  val min: Min[-1, 1] = -1
+     *  ```
+     */
     type Min[X <: Int, Y <: Int] <: Int
+
+    /** Maximum of two `Int` singleton types. Type-level equivalent of `scala.Int.max`.
+     *  ```scala
+     *  val abs: Abs[-1] = 1
+     *  ```
+     */
     type Max[X <: Int, Y <: Int] <: Int
+
+    /** String conversion of an `Int` singleton type. Type-level equivalent of `scala.Int.toString`.
+     *  ```scala
+     *  val abs: ToString[1] = "1"
+     *  ```
+     */
     type ToString[X <: Int] <: String
   }
 
   object boolean {
+
+    /** Negation of a `Boolean` singleton type. Type-level equivalent of `scala.Boolean.unary_!`.
+     *  ```scala
+     *  val notFalse: ![false] = true
+     *  val notTrue: ![true] = false
+     *  ```
+     */
     type ![X <: Boolean] <: Boolean
+
+    /** Exclusive disjunction of two `Boolean` singleton types. Type-level equivalent of `scala.Boolean.^`.
+     * ```scala
+     * val a: true ^ true = false
+     * val b: false ^ true = true
+     * ```
+     */
     @infix type ^[X <: Boolean, Y <: Boolean] <: Boolean
+
+    /** Conjunction of two `Boolean` singleton types. Type-level equivalent of `scala.Boolean.&&`.
+     *  ```scala
+     *  val a: true && true = true
+     *  val b: false && true = false
+     *  ```
+     */
     @infix type &&[X <: Boolean, Y <: Boolean] <: Boolean
+
+    /** Disjunction of two `Boolean` singleton types. Type-level equivalent of `scala.Boolean.||`.
+     * ```scala
+     * val a: true || false = true
+     * val b: false || false = false
+     * ```
+     */
     @infix type ||[X <: Boolean, Y <: Boolean] <: Boolean
   }
 }

tests/pos/singleton-ops-dispatch.scala

@@ -0,0 +1,16 @@
+import scala.compiletime.ops._
+import scala.annotation.infix
+
+object Test {
+  @infix type +[X <: Int | String, Y <: Int | String] = (X, Y) match {
+    case (Int, Int) => int.+[X, Y]
+    case (String, String) => string.+[X, Y]
+    case (String, Int) => string.+[X, int.ToString[Y]]
+    case (Int, String) => string.+[int.ToString[X], Y]
+  }
+
+  val t0: "a" + 1 = "a1"
+  val t1: "a" + "b" = "ab"
+  val t2: 1 + "b" = "1b"
+  val t3: 1 + 1 = 2
+}