Apply suggestions from code review

Author: Sporarum

docs/_docs/reference/contextual/derivation.md

@@ -5,8 +5,8 @@ movedTo: https://docs.scala-lang.org/scala3/reference/contextual/derivation.html
 ---
 
 Type class derivation is a way to automatically generate given instances for type classes which satisfy some simple
-conditions. A type class in this sense is any trait or class with a type parameter determining the type being operated
-on. Common examples are `Eq`, `Ordering`, or `Show`. For example, given the following `Tree` algebraic data type
+conditions. A type class in this sense is any trait or class with a single type parameter determining the type being operated
+on, and the special case `CanEqual`. Common examples are `Eq`, `Ordering`, or `Show`. For example, given the following `Tree` algebraic data type
 (ADT):
 
 ```scala
@@ -35,7 +35,7 @@ given [T: Ordering]: Ordering[Option[T]] = Ordering.derived
 It is discouraged to directly refer to the `derived` member if you can use a `derives` clause instead.
 
 ## Exact mechanism
-In the following, a parameter enumerations where the first index is bigger than the last means there is actually no paramers, for example: `A[T_2, ..., T_1]` means `A`.
+In the following, when type arguments are enumerated and the first index evaluates to a larger value than the last, then there are actually no arguments, for example: `A[T_2, ..., T_1]` means `A`.
 
 For a class/trait/object/enum `DerivingType[T_1, ..., T_N] derives TC`, a derived instance is created in `DerivingType`'s companion object (or `DerivingType` itself if it is an object).
 
@@ -47,11 +47,12 @@ given [...]: TC[ ... DerivingType[...] ... ] = TC.derived
 
 **Note:** `TC.derived` is a normal access, therefore if there are multiple definitions of `TC.derived`, overloading resolution applies.
 
-What the derived instance precisely looks like depends on the specifics of `DerivingType` and `TC`, the first condition is the arity of `TC`:
+What the derived instance precisely looks like depends on the specifics of `DerivingType` and `TC`, we first examine `TC`:
 
 ### `TC` takes 1 parameter
 
-Therefore `TC` is defined as `TC[F[A_1, ..., A_K]]` (`TC[F]` if `K == 0`), there are two further cases depending on the `A_i`s:
+Therefore `TC` is defined as `TC[F[A_1, ..., A_K]]` (`TC[F]` if `K == 0`) for some `F`.
+There are two further cases depending on the kinds of arguments:
 
 #### `F` and all arguments of `DerivingType` have kind `*`
 
@@ -60,18 +61,31 @@ The generated instance is then:
 given [T_1: TC, ..., T_N: TC]: TC[DerivingType[T_1, ..., T_N]] = TC.derived
 ```
 
+This is the most common case, and is the one that was highlighted in the introduction.
+
 **Note:** If `N == 0` the above means:
 ```scala
 given TC[DerivingType] = TC.derived
 ```
+For example, the class
+```scala
+case class Point(x: Int, y: Int) derives Ordering
+```
+generates the instance
+```scala
+object Point:
+  ...
+  given Ordering[Point] = Ordering.derived
+```
+
 
 #### `F` and `DerivingType` have parameters of matching kind on the right
-This section concers cases where you can pair arguments of `F` and `DerivingType` starting from the right such that they have the same kinds pairwise, and all arguments of `F` or `DerivingType` (or both) are used up.
+This section covers cases where you can pair arguments of `F` and `DerivingType` starting from the right such that they have the same kinds pairwise, and all arguments of `F` or `DerivingType` (or both) are used up.
 `F` must also have at least one parameter.
 
 The general shape will then be:
 ```scala
-given [...]: TC[ [...] => DerivingType[...] ] = TC.derived
+given [...]: TC[ [...] =>> DerivingType[...] ] = TC.derived
 ```
 Where of course `TC` and `DerivingType` are applied to types of the correct kind.
 
@@ -96,10 +110,7 @@ If `TC` takes less arguments than `DerivingType` (`K < N`), we fill in the leftm
 given [T_1, ... T_(N-K)]: TC[[A_1, ..., A_K] =>> DerivingType[T_1, ... T_(N-K), A_1, ..., A_K]] = TC.derived
 ```
 
-### `TC` takes 2 parameters
-
-Is `TC` the `CanEqual` type class ?
-If yes, proceed as follows, otherwise go to [`TC` is not valid for automatic derivation](#tc-is-not-valid-for-automatic-derivation).
+### `TC` is the `CanEqual` type class
 
 We have therefore: `DerivingType[T_1, ..., T_N] derives CanEqual`.
 
@@ -115,9 +126,23 @@ given [T_1L, T_1R, ..., T_NL, T_NR]                            // every paramete
 
 The bounds of `T_i`s are handled correctly, for example: `T_2 <: T_1` becomes `T_2L <: T_1L`.
 
+For example, the class
+```scala
+class MyClass[A, G[_]](a: A, b: G[B]) derives CanEqual
+```
+generates the following given instance:
+```scala
+object MyClass:
+  ...
+  given [A_L, A_R, G_L[_], G_R[_]](using CanEqual[A_L, B_L]): CanEqual[MyClass[A_L, G_L], MyClass[A_R, G_R]] = CanEqual.derived
+```
+
 ### `TC` is not valid for automatic derivation
 
-Throw some error.
+Throw an error.
+
+The exact error depends on which of the above conditions failed.
+As an example, if `TC` takes more than 1 parameter and is not `CanEqual`, the error is `DerivingType cannot be unified with the type argument of TC`.
 
 All data types can have a `derives` clause. The rest of this document focuses primarily on data types which also have a given instance
 of the `Mirror` type class available.