Better explanation for how to use FunctionBuilder to deal with variable translation

lib/frontend/src/lib.rs

@@ -1,12 +1,43 @@
 //! Cranelift IR builder library.
 //!
 //! Provides a straightforward way to create a Cranelift IR function and fill it with instructions
-//! translated from another language. Contains an SSA construction module that lets you translate
-//! your non-SSA variables into SSA Cranelift IR values via `use_var` and `def_var` calls.
+//! corresponding to your source program written in another language.
 //!
 //! To get started, create an [`FunctionBuilderContext`](struct.FunctionBuilderContext.html) and
 //! pass it as an argument to a [`FunctionBuilder`](struct.FunctionBuilder.html).
 //!
+//! # Source Language Variables and Cranelift IR values
+//!
+//! The most interesting feature of this API is that it provides a single way to deal with all your
+//! variable problems. Indeed, the [`FunctionBuilder`](struct.FunctionBuilder.html) struct has a
+//! type parameter `Variable` that should be instantiated with the type of your Source Language
+//! Variables (SLV). Then, through calling the functions
+//! [`declare_var`](struct.FunctionBuilder.html#method.declare_var),
+//! [`def_var`](struct.FunctionBuilder.html#method.def_var) and
+//! [`use_var`](struct.FunctionBuilder.html#method.use_var), the
+//! [`FunctionBuilder`](struct.FunctionBuilder.html) will create for you all the Cranelift IR
+//! values corresponding to your SLVs.
+//!
+//! If a SLV is immutable (defined only once), then it will get mapped to one and only Cranelift IR
+//! value. If a SLV is mutable ([`def_var`](struct.FunctionBuilder.html#method.def_var) multiple
+//! times), then internally a [`SSA`](https://en.wikipedia.org/wiki/Static_single_assignment_form)
+//! construction algorithm will automatically create multiple Cranelift IR values that will be
+//! returned to you by [`use_var`](struct.FunctionBuilder.html#method.use_var) depending on where
+//! you want to use your SLV.
+//!
+//! The morality is that you should use these three functions to handle all your SLVs, even those
+//! that are not present in the source code but artefacts of the translation. For instance, if your
+//! source language is expression-based, then you will need to introduce artifical SLVs to store
+//! intermediate results of the computation of your expressions. Hence The `Variable` type that you
+//! would pass to [`FunctionBuilder`](struct.FunctionBuilder.html) could look like this
+//!
+//! ```
+//! enum Variable {
+//!     OriginalSourceVariable(String),
+//!     IntermediateExpressionVariable(u32)
+//! }
+//! ```
+//!
 //! # Example
 //!
 //! Here is a pseudo-program we want to transform into Cranelift IR: