1 files changed, 34 insertions, 42 deletions
diff --git a/docs/source/lang/volatile.rst b/docs/source/lang/volatile.rst
index a0ef671..276bb6a 100644
--- a/docs/source/lang/volatile.rst
+++ b/docs/source/lang/volatile.rst
@@ -1,37 +1,31 @@
-.. _lang-volatile:
-
-volatile keyword
-================
-
-volatile is a keyword known as a variable *qualifier*, it is
-usually used before the datatype of a variable, to modify the way
-in which the compiler and subsequent program treats the variable.
-
-
-
-Declaring a variable volatile is a directive to the compiler. The
-compiler is software which translates your C/C++ code into the
-machine code, which are the real instructions for the Atmega chip
-in the Arduino.
-
-
+.. highlight:: cpp
 
-Specifically, it directs the compiler to load the variable from RAM
-and not from a storage register, which is a temporary memory
-location where program variables are stored and manipulated. Under
-certain conditions, the value for a variable stored in registers
-can be inaccurate.
+.. _lang-volatile:
 
+``volatile``
+============
 
+The ``volatile`` keyword known is a variable *qualifier*.  It is
+usually used before the datatype of a variable, to modify the way in
+which the compiler treats the variable.
 
-A variable should be declared volatile whenever its value can be
-changed by something beyond the control of the code section in
-which it appears, such as a concurrently executing thread. In the
-Arduino, the only place that this is likely to occur is in sections
-of code associated with interrupts, called an interrupt service
-routine.
+Declaring a variable ``volatile`` is a directive to the compiler. The
+compiler is software which translates your C++ code into the machine
+code, which are the real instructions for the STM32 chip in the
+Maple. (The particular compiler we provide for use with the Maple is a
+version of :ref:`GCC <arm-gcc>`).
 
+Specifically, it directs the compiler to read the variable's value
+fresh every time it is used, rather than "backing up" the value and
+reading from its backup copy. (Compilers often "back up" a variable's
+value in RAM into a storage location called a *register*; this is done
+for efficiency).
 
+A variable should be declared ``volatile`` whenever its value can be
+changed by something beyond the control of the code section in which
+it appears, such as an :ref:`external interrupt
+<external-interrupts>`. On the Maple, the only place that this is
+likely to occur is in sections of code associated with interrupts.
 
 Example
 -------
@@ -43,31 +37,29 @@ Example
     int pin = 13;
     volatile int state = LOW;
 
-    void setup()
-    {
+    void setup() {
       pinMode(pin, OUTPUT);
       attachInterrupt(0, blink, CHANGE);
     }
 
-    void loop()
-    {
+    void loop() {
       digitalWrite(pin, state);
     }
 
-    void blink()
-    {
-      state = !state;
+    void blink() {
+      if (state == HIGH) {
+        state = LOW;
+      } else {
+        // state must be HIGH
+        state = HIGH;
+      }
     }
 
-
-
 See also
 --------
 
-
--  `AttachInterrupt <http://arduino.cc/en/Reference/AttachInterrupt>`_
-
-
-
+- :ref:`External Interrupts <external-interrupts>`
+- :ref:`lang-attachinterrupt`
+- :ref:`lang-detachinterrupt`
 
 .. include:: cc-attribution.txt