Diff: ble/CallChainOfFunctionPointersWithContext.h

Revision:

1179:4ab722f8dca0

Parent:

1177:f9060dc8c5ab

Child:

1183:1589830dbdb7

--- a/ble/CallChainOfFunctionPointersWithContext.h	Wed Apr 06 19:15:28 2016 +0100
+++ b/ble/CallChainOfFunctionPointersWithContext.h	Wed Apr 06 19:15:30 2016 +0100
@@ -55,17 +55,16 @@
  * }
  * @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.
+    /** Create an empty chain.
+     *
+     *  @param size (optional) Initial size of the chain.
      */
     CallChainOfFunctionPointersWithContext() : chainHead(NULL) {
         /* empty */
@@ -75,69 +74,58 @@
         clear();
     }
 
-    /**
-     * Add a function at the front of the chain.
+    /** Add a function at the front of the chain.
      *
-     * @param[in]  function
-     *              A pointer to a void function.
+     *  @param function A pointer to a void function.
      *
-     * @return  The function object created for @p function.
+     *  @returns
+     *  The function object created for '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[in] tptr
-     *              Pointer to the object to call the member function on.
-     * @param[in] mptr
-     *              Pointer to the member function to be called.
+     *  @param tptr Pointer to the object to call the member function on.
+     *  @param mptr Pointer to the member function to be called.
      *
-     * @return  The function object created for @p tptr and @p mptr.
+     *  @returns
+     *  The function object created for 'tptr' and '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[in] func
-     *              The FunctionPointerWithContext to add.
-     *
-     * @return  The function object created for @p func.
+     *  @param func The FunctionPointerWithContext to add.
      */
     pFunctionPointerWithContext_t add(const FunctionPointerWithContext<ContextType>& func) {
         return common_add(new FunctionPointerWithContext<ContextType>(func));
     }
 
-    /**
-     * 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) {
+    /** 
+     * 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) { 
         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());
@@ -153,8 +141,7 @@
         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;
@@ -167,32 +154,26 @@
         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);
     }
 
     /**
-     * Same as call() above, but const.
+     * @brief same as 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();
@@ -201,41 +182,34 @@
     }
 
     /**
-     * Same as call(), but with function call operator.
-     * @code
-     *
+     * @brief same as above 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);
     }
 
     /**
-     * Bool conversion operation.
-     *
-     * @return true if the callchain is not empty and false otherwise.
+     * @brief bool conversion operation
      */
     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;
@@ -248,17 +222,10 @@
     }
 
 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 leaks outside the object.
-     *       so the object can still be seen as logically const even if it is modified.
-     */
+    // 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
     mutable pFunctionPointerWithContext_t currentCalled;