Diff: ble/CallChainOfFunctionPointersWithContext.h

Revision:

1147:79a44226e47a

Parent:

1146:3fbf341b09dd

Child:

1155:e28c7aac64ab

--- a/ble/CallChainOfFunctionPointersWithContext.h	Wed Apr 06 19:14:14 2016 +0100
+++ b/ble/CallChainOfFunctionPointersWithContext.h	Wed Apr 06 19:14:15 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,44 +75,52 @@
         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
+     * Detach a function pointer from a callchain.
      *
-     * @oaram toDetach FunctionPointerWithContext to detach from this callchain
+     * @param[in] toDetach
+     *              FunctionPointerWithContext to detach from this callchain.
      *
-     * @return true if a function pointer has been detached and false otherwise
+     * @return true if a function pointer has been detached and false otherwise.
      */
     bool detach(const FunctionPointerWithContext<ContextType>& toDetach) {
         pFunctionPointerWithContext_t current = chainHead;
@@ -141,7 +150,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,18 +164,24 @@
         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;
@@ -182,8 +198,8 @@
     }
 
     /**
-     * @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);
@@ -196,20 +212,27 @@
      * // 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 +245,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;