From b7d2df9307bb404b5548e8d72ae549a0e867ba10 Mon Sep 17 00:00:00 2001
From: Denis Merigoux <denis.merigoux@gmail.com>
Date: Mon, 6 Aug 2018 11:06:42 +0200
Subject: [PATCH] Rewrote doc with @sunfishcode's comments in mind

---
 lib/frontend/src/lib.rs | 33 ++++++++++++++++++---------------
 1 file changed, 18 insertions(+), 15 deletions(-)

diff --git a/lib/frontend/src/lib.rs b/lib/frontend/src/lib.rs
index ed0b21a30d..969ed227c4 100644
--- a/lib/frontend/src/lib.rs
+++ b/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
-//! 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.
+//! values corresponding to your variables.
 //!
-//! 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.
+//! 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 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
+//!
+//! 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)
 //! }
 //! ```
 //!