1 files changed, 23 insertions, 40 deletions
diff --git a/docs/source/arduino/increment.rst b/docs/source/arduino/increment.rst
index f9e87c9..ea9cb88 100644
--- a/docs/source/arduino/increment.rst
+++ b/docs/source/arduino/increment.rst
@@ -1,58 +1,41 @@
-.. _arduino-increment:
+.. highlight:: cpp
 
-++ (increment) / -- (decrement)
-===============================
+.. _arduino-increment:
 
-Description
------------
+Increment (``++``) and Decrement (``--``)
+=========================================
 
-Increment or decrement a variable
+These operators increment (add one to) or decrement (subtract one
+from) a variable.  If they come before the variable, they return its
+new value; otherwise, they return its old value.
 
+Some quick examples::
 
+    x++;  // adds one to x, and returns the old value of x
+    ++x;  // adds one to x, and returns the new value of x
 
-Syntax
-------
+    x--;   // decrement x by one and returns the old value of x
+    --x;   // decrement x by one and returns the new value of x
 
-::
+A more extended example::
 
-    x++;  // increment x by one and returns the old value of x
-    ++x;  // increment x by one and returns the new value of x
-    
-    x-- ;   // decrement x by one and returns the old value of x 
-    --x ;   // decrement x by one and returns the new value of x  
+    x = 2;
+    y = ++x;      // x now contains 3, y contains 3
+    y = x--;      // x contains 2 again, y still contains 3
 
+.. warning:: Be careful!  You cannot put a space in between the two
+    ``+`` or ``-`` signs.  This example is broken::
 
+        // this line won't compile (notice the extra space):
+        int y = x+ +;
 
 Parameters
 ----------
 
-x: an integer or long (possibly unsigned)
-
-
-
-Returns
--------
-
-The original or newly incremented / decremented value of the
-variable.
-
-
-
-Examples
---------
-
-::
-
-    x = 2;
-    y = ++x;      // x now contains 3, y contains 3
-    y = x--;      // x contains 2 again, y still contains 3 
-
-
+**x**: an integer value (like an ``int``, ``long``, ``unsigned int``,
+etc.).
 
 See also
 --------
 
-`+= <http://arduino.cc/en/Reference/Arithmetic>`_
-`-= <http://arduino.cc/en/Reference/Arithmetic>`_
-
-
+- :ref:`Compound arithmetic operators <arduino-arithmeticcompound>`