Rewrote doc with @sunfishcode's comments in mind

lib/frontend/src/lib.rs

@@ -6,35 +6,38 @@
 //! 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
+//! type parameter `Variable` that should be instantiated with the type of your source language
-//! Variables (SLV). Then, through calling the functions
+//! 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.
+//! values corresponding to your variables.
 //!
-//! If a SLV is immutable (defined only once), then it will get mapped to one and only Cranelift IR
+//! This API has been designed to help you translate your mutable variables into
-//! value. If a SLV is mutable ([`def_var`](struct.FunctionBuilder.html#method.def_var) multiple
+//! [`SSA`](https://en.wikipedia.org/wiki/Static_single_assignment_form) form.
-//! times), then internally a [`SSA`](https://en.wikipedia.org/wiki/Static_single_assignment_form)
+//! [`use_var`](struct.FunctionBuilder.html#method.use_var) will returns the Cranelift IR value
-//! construction algorithm will automatically create multiple Cranelift IR values that will be
+//! that corresponds to your mutable variable at a precise point in the program. However, you know
-//! returned to you by [`use_var`](struct.FunctionBuilder.html#method.use_var) depending on where
+//! beforehand that one of your variables is defined only once, for instance if it is the result
-//! you want to use your SLV.
+//! 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 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
+//! The moral is that you should use these three functions to handle all your mutable variables, even those
-//! source language is expression-based, then you will need to introduce artifical SLVs to store
+//! that are not present in the source code but artefacts of the translation. Hence The `Variable` type that you
-//! 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)
+//!     TranslationArtefact(u32)
 //! }
 //! ```
 //!