docs: add API documentation, improve and translate example

actor/Actor.h

@@ -2,29 +2,83 @@
 #define __LEGUINO_ACTOR_H
 
 
+/**
+ * Constant to refer to output A (use this in the actors' constructor.
+ */
 #define OUT_A 'A'
+
+/**
+ * Constant to refer to output B (use this in the actors' constructor.
+ */
 #define OUT_B 'B'
+
+/**
+ * Constant to refer to output C (use this in the actors' constructor.
+ */
 #define OUT_C 'C'
+
+/**
+ * Constant to refer to output D (use this in the actors' constructor.
+ */
 #define OUT_D 'D'
+
+/**
+ * Constant to refer to output E (use this in the actors' constructor.
+ */
 #define OUT_E 'E'
 
 #define _SWITCHTIME_HIGH_NOTREADY 5
 #define _SWITCHTIME_HIGH_READY 50
 #define _SWITCHTIME_LOW 1
 
 
+/**
+ * <p>
+ * Actors represent active devices you attach to the Leguino board, like
+ * LEGO<sup>&copy;</sup> motors and lights. One actor usually requires one
+ * output, but some actors may also represent a combination of outputs, like
+ * the treads (two motors).
+ * </p>
+ *
+ * <p>
+ * Add actors to your program in the setup function, after initializing Leguino,
+ * using the following example pattern:<br>
+ * <code>leguino.add(drive = new Motor(OUT_A));</code><br>
+ * or<br>
+ * <code>leguino.add(drive = new Tread(OUT_A, OUT_B));</code><br>
+ * or<br>
+ * <code>leguino.add(frontLight = new Light(OUT_C));</code><br>
+ * where <code>drive</code> and <code>frontLight</code> are global variables.
+ * </p>
+ *
+ * <p>
+ * In the main loop, after the regular update call to the Leguino platform,
+ * use the actor's methods to control the outputs, spontaneously or
+ * time-controlled.
+ * </p>
+ */
 class Actor
 {
 	friend SingleActor;
 
-	protected:
-
-		Actor();
-
 	public:
 
+		/**
+		 * Destroys the actor.
+		 * Don't call this method from your program.
+		 */
 		virtual ~Actor();
+
+		/**
+		 * Internal Leguino method to update the actor.
+		 * Don't call this method from your program.
+		 * @param msecs The number of milli-seconds since the last update.
+		 */
 		virtual void update(uint16 timeStep) = NULL;
+
+	protected:
+
+		Actor();
 };
 
 

actor/Light.h

@@ -2,10 +2,21 @@
 #define __LEGUINO_LIGHT_H
 
 
+/**
+ * A Leguino single actor representing a LEGO<sup>&copy;</sup> Technic light.
+ *
+ * @see Actor
+ * @see SingleActor
+ */
 class Light : public SingleActor
 {
 	public:
 
+		/**
+		 * Creates a new light.
+		 * @param output The output the light is connected to.
+		 * Use the constants OUT_A thru OUT_E.
+		 */
 		Light(int8 output);
 };
 

actor/Motor.h

@@ -2,12 +2,43 @@
 #define __LEGUINO_MOTOR_H
 
 
+/**
+ * A Leguino single actor representing a LEGO<sup>&copy;</sup> Technic motor.
+ *
+ * @see Actor
+ * @see SingleActor
+ */
 class Motor : public SingleActor
 {
 	public:
 
+		/**
+		 * Creates a new motor.
+		 * @param output The output the motor is connected to.
+		 * Use the constants OUT_A thru OUT_E.
+		 */
 		Motor(int8 output);
+
+		/**
+		 * Turns on this actor (motor) in reverse, setting its output to -100,
+		 * and disabling any sequence.
+		 * @see on()
+		 * @see off()
+		 */
 		void reverse();
+
+		/**
+		 * Turns on this actor (motor) in reverse, setting its output to -100,
+		 * and disabling any sequence. Waits a given number of milli-seconds,
+		 * then turns it off.<br>
+		 * <b>Note:</b> This method blocks until the delay is over. For
+		 * background value control, use sequences instead.
+		 * @param msecs The number of milli-seconds to wait before turning off
+		 * the motor.
+		 * @see on()
+		 * @see off()
+		 * @see Sequence
+		 */
 		void reverse(uint16 msecs);
 };
 

actor/Sequence.h

@@ -2,20 +2,93 @@
 #define __LEGUINO_SEQUENCE_H
 
 
+/**
+ * <p>
+ * A sequence of single-actor values (e.g. for motors, lights), which Leguino
+ * will activate automatically and in background. Use this for e.g. for
+ * flashing lights or any kind of temporary actor activation that requires
+ * the main program to continue in the mean time.
+ * </p>
+ *
+ * <p>
+ * Use the following code to define and activate a sequence:
+ * <code>Sequence * sequence = new Sequence();<br>
+ * sequence->addStep(100, 500);<br>
+ * sequence->addStep(0, 500);<br>
+ * sequence->setRepeat(true);<br>
+ * light->setSequence(sequence);</code>
+ * </p>
+ */
 class Sequence
 {
 	public:
 
+		/**
+		 * Creates a new sequence. Use global variables or the new operator for
+		 * sequences, to ensure the memory is not freed while active in actors.
+		 */
 		Sequence();
+
+		/**
+		 * Adds a step to the sequence.
+		 * @param value The new value from -100 (full reverse), over 0 (off),
+		 * to 100 (full on).
+		 * @param msecs The number of milli-seconds to hold the value.
+		 */
 		void addStep(int8 value, uint16 msecs);
 
+		/**
+		 * Returns the duration of a given step.
+		 * @param step The 0-indexed step number.
+		 * @return The number of milli-seconds of the step.
+		 */
 		uint16 getDuration(int step);
+
+		/**
+		 * Returns the value of a given step.
+		 * @param step The 0-indexed step number.
+		 * @return The value of the step from -100 (full reverse), over 0 (off),
+		 * to 100 (full on).
+		 */
 		int8 getValue(int step);
+
+		/**
+		 * Returns the number of steps added to this sequence so far.
+		 * @return The number of steps.
+		 */
 		int getSteps();
+
+		/**
+		 * Returns the total duration of all steps.
+		 * @return The total duration of all steps.
+		 */
 		uint16 getTotalDuration();
+
+		/**
+		 * Returns whether the transition of the value of one step to the next
+		 * should be smooth.
+		 * @return Whether the sequence transitions are smooth.
+		 */
 		bool isSmooth();
+
+		/**
+		 * Returns whether the sequence should repeat infinitely.
+		 * @return Whether the sequence should repeat.
+		 */
 		bool isRepeat();
+
+		/**
+		 * Sets whether the transition of the value of one step to the next
+		 * should be smooth.
+		 * @param smooth Whether the sequence transitions are smooth.
+		 */
 		void setSmooth(bool smooth);
+
+		/**
+		 * Sets whether the sequence should repeat infinitely.
+		 * Unset the sequence in the actor (or call stop) to stop the repetition.
+		 * @param repeat Whether the sequence should repeat.
+		 */
 		void setRepeat(bool repeat);
 
 	protected:

actor/SingleActor.h

@@ -2,8 +2,99 @@
 #define __LEGUINO_SINGLEACTOR_H
 
 
+/**
+ * A Leguino actor that requires exactly one output jack (e.g. lights,
+ * simple motors).
+ *
+ * @see Actor
+ * @see Light
+ * @see Motor
+ */
 class SingleActor : public Actor
 {
+	public:
+
+		/**
+		 * Creates a new single actor.
+		 * @param output The output the actor is connected to.
+		 * Use the constants OUT_A thru OUT_E.
+		 */
+		SingleActor(int8 output);
+
+		/**
+		 * Returns the currently set value of the actor, considering instant and
+		 * sequence-controlled values.
+		 * @return The current value from -100 (full reverse), over 0 (off),
+		 * to 100 (full on).
+		 */
+		uint16 getCurrentValue();
+
+		/**
+		 * Returns the currently active sequence of this actor, if any.<br>
+		 * See Sequence for more details.
+		 * @return The currently active sequence, or NULL, if no sequence is
+		 * active (which is usually the case, e.g. for instant values).
+		 * @see Sequence
+		 */
+		Sequence * getSequence();
+
+		/**
+		 * Turns off this actor, setting its output to 0, and disabling any
+		 * sequence.
+		 */
+		void off();
+
+		/**
+		 * Turns on this actor, setting its output to 100, and disabling any
+		 * sequence.
+		 */
+		void on();
+
+		/**
+		 * Turns on this actor for a given period of time, then turns it off.
+		 * Also, disables any active sequence.<br>
+		 * <b>Note:</b> This method blocks until the delay is over. For
+		 * background value control, use sequences instead.
+		 * @param msecs The number of milli-seconds before turning off.
+		 * @see Sequence
+		 */
+		void on(uint16 msecs);
+
+		/**
+		 * Starts a sequence on this actor. Any previous sequence is
+		 * automatically disabled.<br>
+		 * See Sequence for more details.
+		 * @param sequence The new sequence to set.
+		 * @see Sequence
+		 */
+		void setSequence(Sequence * sequence);
+
+		/**
+		 * Sets this actor to a given value and disables any active sequence.
+		 * @param value The new value from -100 (full reverse), over 0 (off),
+		 * to 100 (full on).
+		 */
+		void setValue(int8 value);
+
+		/**
+		 * Sets this actor to a given value, for a given period of time, then
+		 * turns it off. Also, disables any active sequence.<br>
+		 * <b>Note:</b> This method blocks until the delay is over. For
+		 * background value control, use sequences instead.
+		 * @param value The new value from -100 (full reverse), over 0 (off),
+		 * to 100 (full on).
+		 * @param msecs The number of milli-seconds to hold the new value.
+		 * @see Sequence
+		 */
+		void setValue(int8 value, uint16 msecs);
+
+		/**
+		 * Internal Leguino method to update the actor.
+		 * Don't call this method from your program.
+		 * @param msecs The number of milli-seconds since the last update.
+		 */
+		virtual void update(uint16 timeStep);
+
 	protected:
 
 		int8 backwardPin;
@@ -22,19 +113,6 @@ class SingleActor : public Actor
 		void switchDirection(int8 value);
 		void updateOutputPins(uint16 timeStep);
 		void updateSequence(uint16 timeStep);
-
-	public:
-
-		SingleActor(int8 output);
-		uint16 getCurrentValue();
-		Sequence * getSequence();
-		void off();
-		void on();
-		void on(uint16 msecs);
-		void setSequence(Sequence * sequence);
-		void setValue(int8 value);
-		void setValue(int8 value, uint16 msecs);
-		virtual void update(uint16 timeStep);
 };