libuavcan documentation

libuavcan/include/uavcan/node/timer.hpp

@@ -25,10 +25,13 @@ namespace uavcan
 
 class UAVCAN_EXPORT TimerBase;
 
+/**
+ * Objects of this type will be supplied into timer callbacks.
+ */
 struct UAVCAN_EXPORT TimerEvent
 {
-    MonotonicTime scheduled_time;
-    MonotonicTime real_time;
+    MonotonicTime scheduled_time;  ///< Time when the timer callback was expected to be invoked
+    MonotonicTime real_time;       ///< True time when the timer callback was invoked
 
     TimerEvent(MonotonicTime arg_scheduled_time, MonotonicTime arg_real_time)
         : scheduled_time(arg_scheduled_time)
@@ -36,7 +39,9 @@ struct UAVCAN_EXPORT TimerEvent
     { }
 };
 
-
+/**
+ * Inherit this class if you need a timer callback method in your class.
+ */
 class UAVCAN_EXPORT TimerBase : private DeadlineHandler
 {
     MonotonicDuration period_;
@@ -54,16 +59,35 @@ public:
         , period_(MonotonicDuration::getInfinite())
     { }
 
+    /**
+     * Various ways to start the timer - periodically or once.
+     */
     void startOneShotWithDeadline(MonotonicTime deadline);
     void startOneShotWithDelay(MonotonicDuration delay);
     void startPeriodic(MonotonicDuration period);
 
+    /**
+     * Returns period if the timer is in periodic mode.
+     * Returns infinite duration if the timer is in one-shot mode or stopped.
+     */
     MonotonicDuration getPeriod() const { return period_; }
 
+    /**
+     * Implement this method in your class to receive callbacks.
+     */
     virtual void handleTimerEvent(const TimerEvent& event) = 0;
 };
 
-
+/**
+ * Wrapper over TimerBase that forwards callbacks into arbitrary handlers, like
+ * functor objects, member functions or static functions.
+ *
+ * Callback must be set before the first event; otherwise the event will generate a fatal error.
+ *
+ * Also take a look at @ref MethodBinder<>, which may come useful if C++11 features are not available.
+ *
+ * @tparam Callback_    Callback type. Shall accept const reference to TimerEvent as its argument.
+ */
 template <typename Callback_>
 class UAVCAN_EXPORT TimerEventForwarder : public TimerBase
 {
@@ -96,6 +120,10 @@ public:
         , callback_(callback)
     { }
 
+    /**
+     * Get/set the callback object.
+     * Callback must be set before the first event; otherwise the event will generate a fatal error.
+     */
     const Callback& getCallback() const { return callback_; }
     void setCallback(const Callback& callback) { callback_ = callback; }
 };
@@ -103,6 +131,10 @@ public:
 
 #if UAVCAN_CPP_VERSION >= UAVCAN_CPP11
 
+/**
+ * Use this timer in C++11 mode.
+ * Callback type is std::function<>.
+ */
 typedef TimerEventForwarder<std::function<void (const TimerEvent& event)> > Timer;
 
 #endif