Rewrote doc with comments in mind
//! 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
+//! # Mutable 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
+//! type parameter `Variable` that should be instantiated with the type of your source language
+//! variables. 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
+//! values corresponding to your variables.
+//!
+//! This API has been designed to help you translate your mutable variables into
+//! [`SSA`](https://en.wikipedia.org/wiki/Static_single_assignment_form) form.
+//! [`use_var`](struct.FunctionBuilder.html#method.use_var) will returns the Cranelift IR value
+//! that corresponds to your mutable variable at a precise point in the program. However, you know
+//! beforehand that one of your variables is defined only once, for instance if it is the result
+//! of an intermediate expression in an expression-based language, then you can translate it
+//! directly by the Cranelift IR value returned by the instruction builder. Using the
+//! [`use_var`](struct.FunctionBuilder.html#method.use_var) API for such an immutable variable
+//! would also work but with a slight additional overhead (the SSA algorithm does not know
+//! beforehand if a variable is immutable or not).
+//!
+//!
+//! The moral is that you should use these three functions to handle all your mutable variables, even those
+//! that are not present in the source code but artefacts of the translation. Hence The `Variable` type that you
//! would pass to [`FunctionBuilder`](struct.FunctionBuilder.html) could look like this
//!
//! ```
//! enum Variable {
//! OriginalSourceVariable(String),
-//! IntermediateExpressionVariable(u32)
+//! TranslationArtefact(u32)
//! }
//! ```
//!
