Add CanEqual section to derivation.md, Small fixes

Author: Sporarum

docs/_docs/reference/contextual/derivation.md

@@ -31,43 +31,56 @@ More formally, for a class/trait/object/enum `DerivingType derives TC`, the foll
 ```scala
 given TC[DerivingType] = TC.derived
 ```
-* if `DerivingType` has type parameters `[T_1, ... T_N]`
+* if `DerivingType` has type parameters `[T_1, ..., T_N]`
 ```scala
-given [T_1: TC, ... T_N: TC]: TC[DerivingType[T_1, ... T_N]] = TC.derived
+given [T_1: TC, ... T_N: TC]: TC[DerivingType[T_1, ..., T_N]] = TC.derived
 ```
 
 `TC.derived` should be an expression that conforms to the expected type `TC[DerivingType]`, potentially elaborated using term and/or type inference.
 
-**Note:** `TC.derived` is a normal method call, therefore if there are multiple definitions of `TC.derived`, overloading resolution applies.
+**Note:** `TC.derived` is a normal access, therefore if there are multiple definitions of `TC.derived`, overloading resolution applies.
 
-**Note:** `TC.derived` can be used manually, for example to implement `Ordering` for `Option`:
+**Note:** `TC.derived` can be used manually, this is useful when you do not have control over the definition. For example we can implement `Ordering` for `Option`s like so:
 
 ```scala
 given [T: Ordering]: Ordering[Option[T]] = Ordering.derived
 ```
 
-### `Mirror`
+It is discouraged to use `derived` if you can use a `derives` clause instead.
+
+#### CanEqual
+
+With `DerivingType[T_1, ..., T_N] derives CanEqual`, the following instance is created:
+
+```scala
+given [T_1L, T_1R, ..., T_NL, T_NR]
+      (using CanEqual[T_1L, T_1R], ..., CanEqual[T_NL, T_NR]): 
+        CanEqual[DerivingType[T_1L, ..., T_NL], DerivingType[T_1R, ..., T_NR]] =
+          CanEqual.derived
+```
+
+## `Mirror`
 
 
 `Mirror` instances provide information at the type level about the components and labelling of the type.
 They also provide minimal term level infrastructure to allow higher level libraries to provide comprehensive
 derivation support.
 
-Instances of `Mirror` are generated automatically by the compiler
+Instances of the `Mirror` type class are generated automatically by the compiler
 unconditionally for:
 - enums and enum cases,
 - case objects.
 
-Instances of `Mirror` are also generated conditionally for:
+Instances for `Mirror` are also generated conditionally for:
 - case classes where the constructor is visible at the callsite (always true if the companion is not a case object)
 - sealed classes and sealed traits where:
   - there exists at least one child case,
   - each child case is reachable from the parent's definition,
   - if the sealed trait/class has no companion, then each child case is reachable from the callsite through the prefix of the type being mirrored,
-  - and where the compiler can generate a `Mirror` instance for each child case.
+  - and where the compiler can generate a `Mirror` type class instance for each child case.
 
 
-The `Mirror` definition is as follows:
+The `Mirror` type class definition is as follows:
 
 ```scala
 sealed trait Mirror:
@@ -374,7 +387,7 @@ The framework described here enables all three of these approaches without manda
 For a brief discussion on how to use macros to write a type class `derived`
 method please read more at [How to write a type class `derived` method using macros](./derivation-macro.md).
 
-### Syntax
+## Syntax
 
 ```
 Template          ::=  InheritClauses [TemplateBody]
@@ -397,7 +410,7 @@ It is equivalent to the old form
 class A extends B with C { ... }
 ```
 
-### Discussion
+## Discussion
 
 This type class derivation framework is intentionally very small and low-level. There are essentially two pieces of
 infrastructure in compiler-generated `Mirror` instances,