updated serial bootloader spec; other improvements

1 files changed, 66 insertions, 30 deletions

diff --git a/source/arduino/switchcase.rst b/source/arduino/switchcase.rst
index 2ca2793..9f66d0a 100644
--- a/source/arduino/switchcase.rst
+++ b/source/arduino/switchcase.rst
@@ -1,3 +1,5 @@
+.. highlight:: cpp
+
 .. _arduino-switchcase:
 
 switch / case statements
@@ -7,10 +9,7 @@ Like :ref:`if/else <arduino-else>` blocks, A ``switch`` statement
 controls program flow by allowing you to specify different code that
 should be executed under various cases.
 
-Syntax
-------
-
-::
+The general syntax looks like this::
 
     switch (var) {
     case val1:
@@ -28,6 +27,7 @@ Where ``var`` is a variable whose value to investigate, and the
 ``val1``, ``val2`` after each ``case`` are constant values that
 ``var`` might be.
 
+
 Description
 -----------
 
@@ -36,46 +36,82 @@ specified in ``case`` statements. When a ``case`` statement is found
 whose value matches that of the variable, the code in that case
 statement is run.
 
-The ``break`` keyword exits the switch statement, and is typically
-used at the end of each ``case``. Without a ``break``, the ``switch``
-statement will continue executing the following ``case`` expressions
-("falling-through") until a ``break`` (or the end of the switch
-statement) is reached.
+Here's a more concrete example::
 
-Writing ``default:`` instead of a ``case`` statement allows you to
-specify what to do if none of the ``case`` statements matches.  Having
-a ``default:`` is optional (you can leave it out), but if you have
-one, it must appear after all of the ``case`` statements, as shown
-above.
+      switch (var) {
+      case 1:
+          doThing1();
+          break;
+      case 2:
+          doThing2();
+          break;
+      }
+      afterTheSwitch();
 
-``switch`` statements are often used with an ``enum`` value as the
-variable to compare.  In this case, you can write down all of the
-values the ``enum`` takes as ``case`` statements, and be sure you've
-covered all the possibilities.
+In the above example, if ``var == 1``, then the code beginning on the
+line after ``case 1:`` gets executed.  That is, if ``var`` is one,
+``doThing1()`` gets called first, and then the ``break`` statement
+gets executed.
+
+The ``break`` keyword exits the ``switch`` statement, and is typically
+used at the end of each ``case``.  Since there is a ``break`` at the
+end of ``case 1:``, the ``switch`` statement gets exited, and the next
+line to be run is the one which calls ``afterTheSwitch()``.
+
+Without a ``break``, the ``switch`` statement will continue executing
+the following ``case`` expressions ("falling-through") until a
+``break`` (or the end of the switch statement) is reached.  Let's
+pretend the ``switch`` looked like this instead::
 
-Example
--------
+      switch (var) {
+      case 1:
+          doThing1();
+          // no break statement anymore
+      case 2:
+          doThing2();
+          break;
+      }
+      afterTheSwitch();
+
+Now, if ``var`` is one, ``doThing1()`` gets executed like before.
+However, without a ``break``, the code would continue to be executed
+line-by-line, so ``doThing2()`` would be called next.  At this point,
+a ``break`` has been reached, so the program continues by calling
+``afterTheSwitch()``.  This is usually not what you want, which is why
+each ``case`` usually has a ``break`` at the end.
 
-::
+Writing "``default:``" instead of a ``case`` statement allows you to
+specify what to do if none of the ``case`` statements matches.  Having
+a ``default`` is optional (you can leave it out), but if you have one,
+it must appear after all of the ``case`` statements.  Let's add a
+``default`` to the ``switch`` we've been discussing::
 
       switch (var) {
       case 1:
-          //do something when var equals 1
+          doThing1();
           break;
       case 2:
-          //do something when var equals 2
+          doThing2();
           break;
       default:
-          // if nothing else matches, do the default
-          // default is optional
+          doSomethingElse();
       }
+      afterTheSwitch();
 
-See also:
----------
-
-`if...else <http://arduino.cc/en/Reference/Else>`_
+If ``var`` is one, then ``doThing1()`` gets called.  If ``var`` is
+two, ``doThing2()`` gets called.  If ``var`` is anything else,
+``doSomethingElse()`` gets called.  As stated above, a ``default`` is
+optional.  If you're missing one and none of the ``case`` statements
+match, the ``switch`` does nothing at all, as if it wasn't there.
 
+``switch`` statements are often used with an ``enum`` value as the
+variable to compare.  In this case, you can write down all of the
+values the ``enum`` takes as ``case`` statements, and be sure you've
+covered all the possibilities.
 
+See also:
+---------
 
+- :ref:`if...else <arduino-else>`
 
-.. include:: cc-attribution.txt
\ No newline at end of file
+.. include:: cc-attribution.txt