From d7cded57ccad7c192dfd8a705e6cd04dc19c74e4 Mon Sep 17 00:00:00 2001
From: Mike Tsao <mike@sowbug.com>
Date: Wed, 4 Jan 2012 13:22:03 -0800
Subject: [PATCH] Added class documentation per spydergt1's request in issue 6.

---
 G35.h            |  4 ++--
 G35String.h      | 10 ++++++++++
 G35StringGroup.h |  6 ++++++
 LightProgram.h   |  3 +++
 ProgramRunner.h  | 10 ++++++++++
 5 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/G35.h b/G35.h
index db48137..a9d6391 100755
--- a/G35.h
+++ b/G35.h
@@ -32,8 +32,8 @@
 #define COLOR_INDIGO          COLOR(0x6, 0, 0xf)
 #define COLOR_VIOLET          COLOR(0x8, 0, 0xf)
 
-// A virtual class representing a string of G35 lights of arbitrary length.
-// LightPrograms talk to this interface.
+// G35 is an abstract class representing a string of G35 lights of arbitrary
+// length. LightPrograms talk to this interface.
 class G35 {
  public:
   G35();
diff --git a/G35String.h b/G35String.h
index a005169..6554fc8 100644
--- a/G35String.h
+++ b/G35String.h
@@ -12,6 +12,16 @@
 
 #include <G35.h>
 
+// A G35String knows how to talk to a real GE Color Effects light string.
+// In particular, it implements the set_color() method of the G35 interface.
+//
+// These strings need enumerate() to be called before anything else, so that
+// each bulb has an individual address. In many cases, your lights will work
+// as expected even if you forget to call enumerate(), because most programs
+// happen to do the same thing as enumerate() -- namely, they send commands
+// to all bulbs starting with bulb #0 and ending with bulb #N-1. If your
+// light programs look right but fractured, it's because you forgot to call
+// enumerate().
 class G35String : public G35 {
  public:
   // |pin|: the Arduino pin driving this string's data line.
diff --git a/G35StringGroup.h b/G35StringGroup.h
index c19b525..eab2073 100644
--- a/G35StringGroup.h
+++ b/G35StringGroup.h
@@ -12,6 +12,12 @@
 
 #include <G35.h>
 
+// A G35StringGroup takes a set of G35 instances and presents them as a single
+// virtual light string of arbitrary length.
+//
+// A LightProgram that is given a G35StringGroup will then be able to run
+// itself over the whole virtual string, without needing to know the details
+// of which physical string contains which logical bulb.
 class G35StringGroup : public G35 {
  public:
   G35StringGroup();
diff --git a/LightProgram.h b/LightProgram.h
index b150bef..7fabe84 100644
--- a/LightProgram.h
+++ b/LightProgram.h
@@ -14,6 +14,9 @@
 #include <G35.h>
 
 // Interface for light programs.
+//
+// A "light program" is what GE means when they say their lights include 14
+// programs. An example is "Chasing Red, White, and Blue."
 class LightProgram {
  public:
  LightProgram(G35& g35)
diff --git a/ProgramRunner.h b/ProgramRunner.h
index 9829a90..1d10f27 100644
--- a/ProgramRunner.h
+++ b/ProgramRunner.h
@@ -13,6 +13,16 @@
 
 #include <LightProgram.h>
 
+// ProgramRunner manages a collection of LightPrograms.
+//
+// It gives the current program a slice of time to run, decides when it's
+// time to switch to the next program, and asks the program_creator callback
+// to give it the next program when it's time. In Arduino terms, it's what
+// you want to call in your loop() method.
+//
+// switch_program() is public because the application might sometimes want
+// to change programs more frequently, for example if you've implemented
+// a remote control receiver.
 class ProgramRunner {
  public:
  ProgramRunner(LightProgram* (*program_creator)(uint8_t program_index),