wip

Author: biboudis

docs/docs/reference/metaprogramming/inline.md

@@ -3,7 +3,7 @@ layout: doc-page
 title: Inline
 ---
 
-## Inline (whitebox/blackbox)
+## Inline (blackbox/whitebox)
 
 `inline` is a new [soft modifier](../soft-modifier.html) that guarantees that a
 definition will be inlined at the point of use. Example:
@@ -33,9 +33,9 @@ object Logger {
 The `Config` object contains a definition of the **inline value** `logging`.
 This means that `logging` is treated as a _constant value_, equivalent to its
 right-hand side `false`. The right-hand side of such an `inline val` must itself
-be a [constant expression](#the-definition-of-constant-expression). Used in this
+be a [constant expression](https://scala-lang.org/files/archive/spec/2.12/06-expressions.html#constant-expressions). Used in this
 way, `inline` is equivalent to Java and Scala 2's `final`. `final` meaning
-"constant" is still supported in Dotty, but will be phased out.
+_inlined constant_ is still supported in Dotty, but will be phased out.
 
 The `Logger` object contains a definition of the **inline method** `log`.
 This method will always be inlined at the point of call.
@@ -195,27 +195,27 @@ where vals are used for value parameter bindings and defs are used for by-name
 parameter bindings. If an argument `E_i` is a simple variable reference `y`, the
 corresponding binding is omitted and `y` is used instead of `x_i` in `B`.
 
-If a inline modifier is given for parameters, corresponding arguments must be
+If a `inline` modifier is given for parameters, corresponding arguments must be
 pure expressions of constant type.
 
 #### The definition of constant expression
 
 Right-hand sides of inline values and of arguments for inline parameters must be
 constant expressions in the sense defined by the [SLS §
 6.24](https://www.scala-lang.org/files/archive/spec/2.12/06-expressions.html#constant-expressions),
-including "platform-specific" extensions such as constant folding of pure
+including _platform-specific_ extensions such as constant folding of pure
 numeric computations.
 
 ### Specializing Inline (Whitebox)
 
-Inline methods support the `<: T` return syntax. This means that the return type
+Inline methods support the ` <: T` return type syntax. This means that the return type
 of the inline method is going to be specialized to a more precise type upon
 expansion.
 
 Consider the example below where the inline method `choose` can return an object
 of any of the two dynamic types. The subtype relationship is `B <: A`. Since we
-use the specializing inline syntax, the static types of the vals are inferred
-accordingly. Consequently, calling `meth` on `obj2` is a compile-time error.
+use the specializing inline syntax, the static types of the `val`s are inferred
+accordingly. Consequently, calling `meth` on `obj2` is not a compile-time error as `obj2` will be of type `B`.
 
 ```scala
 class A
@@ -224,7 +224,7 @@ class B extends A {
 }
 
 inline def choose(b: Boolean) <: A = {
-  if(b) new A()
+  if (b) new A()
   else new B()
 }
 
@@ -255,8 +255,8 @@ inline def g(x: Any) <: Any = inline x match {
   case x: Double => x
 }
 
-g(1.0d): 1.0d
-val t: (String, String) = g("test")
+g(1.0d) // Has type 1.0d which is a subtype of Double
+g("test") // Has type (String, String)
 ```
 
 The scrutinee `x` is examined statically and the inline match is reduced
@@ -276,14 +276,36 @@ inline def toInt(n: Nat) <: Int = inline n match {
   case Succ(n1) => toInt(n1) + 1
 }
 
-final val two = toInt(Succ(Succ(Zero)))
-val two_ : 2 = two
+final val natTwo = toInt(Succ(Succ(Zero)))
+val intTwo: 2 = natTwo
 ```
 
-`two` is inferred to have the singleton type 2.
+`natTwo` is inferred to have the singleton type 2.
 
 #### scala.compiletime._
 
+This package contains helper definitions providing support for compile time
+operations over values.
+
+##### Const Value & Const Value Opt
+
+`constvalue` is a function that produces the constant value represented by a
+type.
+
+```scala
+inline def toIntC[N] <: Int =
+  inline scala.compiletime.constValue[N] match {
+    case 0 => 0
+    case _: scala.compiletime.S[n1] => 1 + toIntC[n1]
+  }
+
+final val ctwo = toIntC[2]
+```
+
+`constValueOpt` is the same as `constValue`, however returning an `Option[T]`
+enabling us to handle situations where a value is not present.
+
+
 ##### Erased Value
 
 We have seen so far inline methods that take terms (tuples and integers) as
@@ -345,20 +367,6 @@ final val two = toInt[Succ[Succ[Zero]]]
 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).
 
-##### Const Value & Const Value Opt
-
-`constvalue` is a function that produces the constant value represented by a
-type.
-
-```scala
-inline def toIntC[N] <: Int =
-  inline scala.compiletime.constValue[N] match {
-    case 0 => 0
-    case _: scala.compiletime.S[n1] => 1 + toIntC[n1]
-  }
-
-final val ctwo = toIntC[2]
-```
 
 #### Implicit Match