1 files changed, 70 insertions, 40 deletions
diff --git a/docs/source/arduino/comparison.rst b/docs/source/arduino/comparison.rst
index b87e05b..85c2118 100644
--- a/docs/source/arduino/comparison.rst
+++ b/docs/source/arduino/comparison.rst
@@ -1,54 +1,84 @@
+.. highlight:: cpp
+
 .. _arduino-comparison:
 
-Arduino/Processing Language Comparison
-======================================
+Comparison Operators
+====================
+
+The comparison operators ``==``, ``!=``, ``<``, ``>``, ``<=``, and
+``>=`` are used to compare two numbers.  They are :ref:`true
+<arduino-constants-true>` when the comparison is true, and :ref:`false
+<arduino-constants-false>` otherwise.  They are based on the symbols
+=, ≠, <, >, ≤, and ≥ from mathematics.
+
+Here are some examples, with their meaning in comments::
+
+     // "eq" is true when x is equal to y
+     bool eq = (x == y);
+
+     // "neq" is true when x is different than y
+     bool neq = (x != y);
+
+     // "lt" is true when x is less than, but NOT equal to, y
+     bool lt = (x <  y);
+
+     // "gt" is true when x is greater than, but NOT equal to, y
+     bool gt = (x >  y);
+
+     // "lte" is true when x is less than or equal to y
+     bool lte = (x <= y);
+
+     // "gte" is true when x is greater than or equal to y
+     bool gte = (x >= y);
 
-The Arduino language (based on Wiring) is implemented in C/C++, and
-therefore has some differences from the Processing language, which
-is based on Java.
+The parentheses are optional; they are present only for clarity.  For
+example, the following two lines are the same::
 
+    bool eq = x == y;
 
+    bool eq = (x == y);
 
-Arrays
-~~~~~~
+Uses
+----
 
-*Arduino*
-*Processing*
-int bar[8];
-bar[0] = 1;
-int[] bar = new int[8];
-bar[0] = 1;
-int foo[] = { 0, 1, 2 };
-int foo[] = { 0, 1, 2 };
-*or*
-int[] foo = { 0, 1, 2 };
+Comparison operators, along with :ref:`boolean operators
+<arduino-boolean>`, are useful inside the conditionals of :ref:`if
+<arduino-if>` statements.  Here's one example::
 
+    if (x < 50) {
+       // only execute these lines if x is less than 50
+       SerialUSB.println("delaying:");
+       SerialUSB.println(x);
+       delay(x);
+    }
 
-Loops
-~~~~~
+.. warning::
+   Beware of accidentally using the single equal sign (``=``) when you
+   meant to test if two numbers are equal (``==``).  This is a common
+   mistake inside of ``if`` statement conditionals, e.g.::
 
-*Arduino*
-*Processing*
-int i;
-for (i = 0; i < 5; i++) { ... }
-for (int i = 0; i < 5; i++) { ... }
+       // DON'T MAKE THIS MISTAKE
+       if (x = 10) {
+          // body
+       }
 
+   The single equal sign is the assignment operator, and sets x to 10
+   (puts the value 10 into the variable x).  Instead use the double equal
+   sign (e.g. ``if (x == 10)``), which is the comparison operator, and
+   tests *whether* x is equal to 10 or not. The latter statement is only
+   true if x equals 10, but the former statement will always be true.
 
-Printing
-~~~~~~~~
+   This is because C evaluates the statement ``if (x=10)`` as follows: 10
+   is assigned to x (remember that the single equal sign is the
+   :ref:`assignment operator <arduino-assignment>`), so x now
+   contains 10. Then the 'if' conditional evaluates 10, which evaluates
+   to :ref:`true <arduino-constants-true>`, since any non-zero number
+   evaluates to ``true``.
 
-*Arduino*
-*Processing*
-Serial.println("hello world");
-println("hello world");
-int i = 5;
-Serial.println(i);
-int i = 5;
-println(i);
-int i = 5;
-Serial.print("i = ");
-Serial.print(i);
-Serial.println();
-int i = 5;
-println("i = " + i);
+   Consequently, the conditional of an ``if`` statement like ``if (x =
+   10) {...}`` will always evaluate to ``true``, and the variable x
+   will be set to 10, which is probably not what you meant.
 
+   (This sometimes has uses, though, so just because an assignment
+   appears within a conditional doesn't mean it's automatically wrong.
+   Be careful to know what you mean.)