Diff: Controller.h

Revision:

39:cb67926712d4

Parent:

38:930469a33001

Child:

45:bb33913d4fd2

Child:

53:4e3ee54157ad

--- a/Controller.h	Tue Jun 14 17:49:08 2016 +0000
+++ b/Controller.h	Tue Jun 14 19:11:19 2016 +0000
@@ -5,34 +5,92 @@
 
 #include "rtos.h"
 
+/** The base class for everything which interfaces with sensors or actuators.
+ * Extending classes must implement \a std::string \a get_name() and \a void \a update()
+ */
 class Controller {
     public:
+    
+        /**
+         * Initializes the Controller.
+         * @param threaded whether or not the controller should be threaded.
+         * @param interval_ms delay between each iteration, only if threaded is set to \a true.
+        */
         Controller(bool threaded, int interval_ms);
         
+        /**
+         * Returns the name of this Controller. Must be implemented by extending classes.
+         * @return The name of this Controller.
+        */        
         virtual std::string get_name() = 0;
         
+        /**
+         * Returns whether or not this Controller is being threaded.
+         * @return \a true if this Controller is being threaded, \a false otherwise.
+        */   
         bool is_threaded();
-        
+
+        /**
+         * If this Controller is not threaded, \a update() is called. Otherwise, the first time a thread is spawned which repeatedly calls \a update().
+         * When the thread has already been spawned no action is taken.
+        */           
         void run();
-                
+
+        /**
+         * Returns the interval between each iteration if threaded.
+         * @return \a interval_ms as specified in the constructor.
+        */                 
         int get_interval_ms();
-        
+
+        /**
+         * Sets the underlying RTOS thread priority.
+         * @see cmis_os.h
+        */           
         void set_priority(osPriority priority);
-        
+
+        /**
+         * Returns the thread priority.
+         * @return the thread priority.
+        */           
         osPriority get_priority();
         
     protected:
         virtual void update() = 0;
         
+        /**
+         * The number of times \a run() is called.
+        */
         unsigned long num_iters;
                 
     private:
+        /**
+         * Whether or not this Controller is threaded.
+        */    
         bool threaded;
+        
+        /**
+         * Whether or not a thread has been spawned for this Controller.
+        */        
         bool has_spawned;
+        
+        /**
+         * Pointer to the spawned thread if \a has_spawned is \a true, undefined otherwise.
+        */
         Thread *ctrl_thread;
+        
+        /**
+         * Interval in ms between each iteration, only if \a threaded is set to \a true.
+        */
         int interval_ms;
+        
+        /**
+         * Priority of the underlying thread.
+        */        
         osPriority prio;
         
+        /**
+         * This function is called when the thread is created, it repeatedly calls \a run() and waits for \a interval_ms milliseconds.
+        */        
         static void thread_stub(void const *args);
 };