Add preliminary chapter on kinds

Author: varkor

src/SUMMARY.md

@@ -38,6 +38,7 @@
 - [The HIR (High-level IR)](./hir.md)
     - [Lowering AST to HIR](./lowering.md)
 - [The `ty` module: representing types](./ty.md)
+- [Kinds](./kinds.md)
 - [Type inference](./type-inference.md)
 - [Trait solving (old-style)](./traits/resolution.md)
     - [Higher-ranked trait bounds](./traits/hrtb.md)

src/kinds.md

@@ -0,0 +1,31 @@
+# Kinds
+A `ty::subst::Kind<'tcx>` represents some entity in the type system: currently
+either a type (`Ty<'tcx>`) or a lifetime (`ty::Region<'tcx>`), though in the
+future this will also include constants (`ty::Const<'tcx>`) to facilitate the
+use of const generics. `Kind` is used for type and lifetime substitution (from
+abstract type and lifetime parameters to concrete types and lifetimes).
+
+## `UnpackedKind`
+As `Kind` itself is not type-safe (see [`Kind`](#kind)), the `UnpackedKind` enum
+provides a more convenient and safe interface for dealing with kinds. To
+convert from an `UnpackedKind` to a `Kind`, you can call `Kind::from` (or
+`.into`). It should not be necessary to convert a `Kind` to an `UnpackedKind`:
+instead, you should prefer to deal with `UnpackedKind`, converting it only when
+passing it to `Subst` methods.
+
+## `Kind`
+The actual `Kind` struct is optimised for space, storing the type or lifetime
+as an interned pointer containing a mask identifying its kind (in the lowest
+2 bits).
+
+## `Subst`
+`ty::subst::Subst<'tcx>` is simply defined as a slice of `Kind<'tcx>`s
+and acts as an ordered list of substitutions from kind parameters (i.e.
+type and lifetime parameters) to kinds.
+
+For example, given a `HashMap<K, V>` with two type parameters, `K` and `V`, an
+instantiation of the parameters, for example `HashMap<i32, u32>`, would be
+represented by the substitution `&'tcx [tcx.types.i32, tcx.types.u32]`.
+
+`Subst` provides various convenience methods to instantiant substitutions
+given item definitions.

src/ty.md

@@ -141,8 +141,8 @@ In addition to types, there are a number of other arena-allocated data
 structures that you can allocate, and which are found in this
 module. Here are a few examples:
 
-- `Substs`, allocated with `mk_substs` – this will intern a slice of types,
-  often used to specify the values to be substituted for generics
+- [`Substs`][subst], allocated with `mk_substs` – this will intern a slice of
+  types, often used to specify the values to be substituted for generics
   (e.g. `HashMap<i32, u32>` would be represented as a slice
   `&'tcx [tcx.types.i32, tcx.types.u32]`).
 - `TraitRef`, typically passed by value – a **trait reference**
@@ -153,6 +153,8 @@ module. Here are a few examples:
 - `Predicate` defines something the trait system has to prove (see `traits`
   module).
 
+[subst]: ./kinds.html#subst
+
 ### Import conventions
 
 Although there is no hard and fast rule, the `ty` module tends to be used like