arduino language reference nearing completion, properly CC-BY-SA 3.0 attributed

1 files changed, 37 insertions, 54 deletions

diff --git a/source/arduino/static.rst b/source/arduino/static.rst
index 1c0340e..b292891 100644
--- a/source/arduino/static.rst
+++ b/source/arduino/static.rst
@@ -1,71 +1,54 @@
+.. highlight:: cpp
+
 .. _arduino-static:
 
 Static
 ======
 
-The static keyword is used to create variables that are visible to
-only one function. However unlike local variables that get created
-and destroyed every time a function is called, static variables
-persist beyond the function call, preserving their data between
-function calls.
-
-
+The ``static`` keyword can be used to create variables that are
+visible to only one function. However, unlike local variables that get
+created and destroyed every time a function is called, ``static``
+variables persist beyond the function call, preserving their data
+between function calls.
 
-Variables declared as static will only be created and initialized
+Variables declared as ``static`` will only be created and initialized
 the first time a function is called.
 
-
+.. note:: This is only one use of the ``static`` keyword in C++.  It
+   has some other important uses that are outside the scope of this
+   documentation; consult a reliable C++ reference for details.
 
 Example
 -------
 
-::
+One use case for ``static`` variables is implementing counters that
+last longer than the functions which need them, but shouldn't be
+shared to other functions.  Here's an example::
 
-    
-    
-    /* RandomWalk
-    * Paul Badger 2007
-    * RandomWalk wanders up and down randomly between two
-    * endpoints. The maximum move in one loop is governed by
-    * the parameter "stepsize".
-    * A static variable is moved up and down a random amount.
-    * This technique is also known as "pink noise" and "drunken walk".
-    */
-    
-    #define randomWalkLowRange -20
-    #define randomWalkHighRange 20
-    int stepsize;
-    
-    int thisTime;
-    int total;
-    
-    void setup()
-    {
-      Serial.begin(9600);
+    void setup() {
+        SerialUSB.begin();
     }
-    
-    void loop()
-    {        //  tetst randomWalk function
-      stepsize = 5;
-      thisTime = randomWalk(stepsize);
-      Serial.println(thisTime);
-       delay(10);
+
+    void loop() {
+        int reading;
+        if (timeToReadSensors()) {
+            reading = readSensors();
+        }
+        // do something with reading
     }
-    
-    int randomWalk(int moveSize){
-      static int  place;     // variable to store value in random walk - declared static so that it stores
-                             // values in between function calls, but no other functions can change its value
-    
-      place = place + (random(-moveSize, moveSize + 1));
-    
-      if (place < randomWalkLowRange){                    // check lower and upper limits
-        place = place + (randomWalkLowRange - place);     // reflect number back in positive direction
-      }
-      else if(place > randomWalkHighRange){
-        place = place - (place - randomWalkHighRange);     // reflect number back in negative direction
-      }
-    
-      return place;
+
+    int readSensors() {
+        static int numSensorReadings = 0;
+        numSensorReadings++;
+        if (numSensorReadings % 100 == 0) {
+            SerialUSB.print("just got to another 100 sensor readings");
+        }
+        return analogRead(...);
     }
-    
 
+In this example, the static variable ``numSensorReadings`` is
+initialized to zero the first time ``readSensors()`` is called, and
+then incremented, so it starts out at one.  Subsequent calls to
+``readSensors()`` won't reset ``numSensorReadings`` to zero, because
+it was declared ``static``.  Thus, ``numSensorReadings`` is a count of
+the number of times that ``readSensors()`` has been called.