Diff: ble/CallChainOfFunctionPointersWithContext.h

Revision:

1183:1589830dbdb7

Parent:

1179:4ab722f8dca0

--- a/ble/CallChainOfFunctionPointersWithContext.h	Wed Apr 06 19:15:34 2016 +0100
+++ b/ble/CallChainOfFunctionPointersWithContext.h	Wed Apr 06 19:15:36 2016 +0100
@@ -55,16 +55,17 @@
  * }
  * @endcode
  */
-
 template <typename ContextType>
 class CallChainOfFunctionPointersWithContext : public SafeBool<CallChainOfFunctionPointersWithContext<ContextType> > {
 public:
+    /**
+     * The type of each callback in the callchain.
+     */
     typedef FunctionPointerWithContext<ContextType> *pFunctionPointerWithContext_t;
 
 public:
-    /** Create an empty chain.
-     *
-     *  @param size (optional) Initial size of the chain.
+    /**
+     * Create an empty chain.
      */
     CallChainOfFunctionPointersWithContext() : chainHead(NULL) {
         /* empty */
@@ -74,58 +75,69 @@
         clear();
     }
 
-    /** Add a function at the front of the chain.
+    /**
+     * Add a function at the front of the chain.
      *
-     *  @param function A pointer to a void function.
+     * @param[in]  function
+     *              A pointer to a void function.
      *
-     *  @returns
-     *  The function object created for 'function'.
+     * @return  The function object created for @p function.
      */
     pFunctionPointerWithContext_t add(void (*function)(ContextType context)) {
         return common_add(new FunctionPointerWithContext<ContextType>(function));
     }
 
-    /** Add a function at the front of the chain.
+    /**
+     * Add a function at the front of the chain.
      *
-     *  @param tptr Pointer to the object to call the member function on.
-     *  @param mptr Pointer to the member function to be called.
+     * @param[in] tptr
+     *              Pointer to the object to call the member function on.
+     * @param[in] mptr
+     *              Pointer to the member function to be called.
      *
-     *  @returns
-     *  The function object created for 'tptr' and 'mptr'.
+     * @return  The function object created for @p tptr and @p mptr.
      */
     template<typename T>
     pFunctionPointerWithContext_t add(T *tptr, void (T::*mptr)(ContextType context)) {
         return common_add(new FunctionPointerWithContext<ContextType>(tptr, mptr));
     }
 
-    /** Add a function at the front of the chain.
+    /**
+     * Add a function at the front of the chain.
      *
-     *  @param func The FunctionPointerWithContext to add.
+     * @param[in] func
+     *              The FunctionPointerWithContext to add.
+     *
+     * @return  The function object created for @p func.
      */
     pFunctionPointerWithContext_t add(const FunctionPointerWithContext<ContextType>& func) {
         return common_add(new FunctionPointerWithContext<ContextType>(func));
     }
 
-    /** 
-     * Detach a function pointer from a callchain
-     * 
-     * @oaram toDetach FunctionPointerWithContext to detach from this callchain
-     * 
-     * @return true if a function pointer has been detached and false otherwise
-     */ 
-    bool detach(const FunctionPointerWithContext<ContextType>& toDetach) { 
+    /**
+     * Detach a function pointer from a callchain.
+     *
+     * @param[in] toDetach
+     *              FunctionPointerWithContext to detach from this callchain.
+     *
+     * @return true if a function pointer has been detached and false otherwise.
+     *
+     * @note It is safe to remove a function pointer while the chain is
+     *       traversed by call(ContextType).
+     */
+    bool detach(const FunctionPointerWithContext<ContextType>& toDetach) {
         pFunctionPointerWithContext_t current = chainHead;
         pFunctionPointerWithContext_t previous = NULL;
 
         while (current) {
-            if(*current == toDetach) { 
+            if(*current == toDetach) {
                 if(previous == NULL) {
-                    if(currentCalled == current) { 
+                    if(currentCalled == current) {
                         currentCalled = NULL;
                     }
                     chainHead = current->getNext();
                 } else {
-                    if(currentCalled == current) { 
+                    if(currentCalled == current) {
                         currentCalled = previous;
                     }
                     previous->chainAsNext(current->getNext());
@@ -141,7 +153,8 @@
         return false;
     }
 
-    /** Clear the call chain (remove all functions in the chain).
+    /**
+     * Clear the call chain (remove all functions in the chain).
      */
     void clear(void) {
         pFunctionPointerWithContext_t fptr = chainHead;
@@ -154,26 +167,32 @@
         chainHead = NULL;
     }
 
+    /**
+     * Check whether the callchain contains any callbacks.
+     *
+     * @return true if the callchain is not empty and false otherwise.
+     */
     bool hasCallbacksAttached(void) const {
         return (chainHead != NULL);
     }
 
-    /** Call all the functions in the chain in sequence
+    /**
+     * Call all the functions in the chain in sequence.
      */
     void call(ContextType context) {
         ((const CallChainOfFunctionPointersWithContext*) this)->call(context);
     }
 
     /**
-     * @brief same as above but const 
+     * Same as call() above, but const.
      */
     void call(ContextType context) const {
         currentCalled = chainHead;
 
-        while(currentCalled) { 
+        while(currentCalled) {
             currentCalled->call(context);
             // if this was the head and the call removed the head
-            if(currentCalled == NULL) { 
+            if(currentCalled == NULL) {
                 currentCalled = chainHead;
             } else {
                 currentCalled = currentCalled->getNext();
@@ -182,34 +201,41 @@
     }
 
     /**
-     * @brief same as above but with function call operator
-     * \code
-     * 
+     * Same as call(), but with function call operator.
+     * @code
+     *
      * void first(bool);
      * void second(bool);
-     * 
+     *
      * CallChainOfFunctionPointerWithContext<bool> foo;
-     * 
+     *
      * foo.attach(first);
      * foo.attach(second);
-     * 
+     *
      * // call the callchain like a function
      * foo(true);
-     * 
-     * \endcode
+     *
+     * @endcode
      */
     void operator()(ContextType context) const {
         call(context);
     }
 
     /**
-     * @brief bool conversion operation
+     * Bool conversion operation.
+     *
+     * @return true if the callchain is not empty and false otherwise.
      */
     bool toBool() const {
         return chainHead != NULL;
     }
 
 private:
+    /**
+     * Add a callback to the head of the callchain.
+     *
+     * @return A pointer to the head of the callchain.
+     */
     pFunctionPointerWithContext_t common_add(pFunctionPointerWithContext_t pf) {
         if (chainHead == NULL) {
             chainHead = pf;
@@ -222,10 +248,17 @@
     }
 
 private:
+    /**
+     * A pointer to the first callback in the callchain or NULL if the callchain is empty.
+     */
     pFunctionPointerWithContext_t chainHead;
-    // iterator during a function call, this has to be mutable because the call function is const.
-    // Note: mutable is the correct behaviour here, the iterator never leak outside the object.
-    // So the object can still be seen as logically const even if it change its internal state
+
+    /**
+     * Iterator during a function call, this has to be mutable because the call function is const.
+     *
+     * @note Mutable is the correct behaviour here, the iterator never leaks outside the object.
+     *       so the object can still be seen as logically const even if it is modified.
+     */
     mutable pFunctionPointerWithContext_t currentCalled;