Process code review for Ticket EMBB-520, resolve cpplint issues

containers_cpp/include/embb/containers/lock_free_tree_value_pool.h

@@ -285,8 +285,13 @@ class LockFreeTreeValuePool {
    * by it. However, usually one wants to guarantee a minimal capacity. The
    * count of elements, that must be given to the pool when to guarantee \c
    * capacity elements is computed using this function.
+   *
+   * \return count of indices the pool has to be initialized with
    */
-  static size_t GetMinimumElementCountForGuaranteedCapacity(size_t capacity);
+  static size_t GetMinimumElementCountForGuaranteedCapacity(
+    size_t capacity
+    /**< [IN] count of indices that shall be guaranteed */);
+    );
 
   /**
    * Destructs the pool.

containers_cpp/include/embb/containers/object_pool.h

@@ -114,6 +114,7 @@ class ObjectPool {
   bool IsContained(const Type &obj) const;
   int GetIndexOfObject(const Type &obj) const;
   Type* AllocateRaw();
+
  public:
   /**
    * Constructs an object pool with capacity \c capacity.

containers_cpp/include/embb/containers/wait_free_array_value_pool.h

@@ -39,12 +39,30 @@ namespace containers {
  * \ingroup CPP_CONCEPT
  * \{
  * \par Description
- * A value pool is a fixed-size multiset of elements, where each element has a
- * unique index. The elements cannot be modified and are given at construction
- * time (by providing first/last iterators). A value pool provides two
- * operations: \c Allocate and \c Free. \c Allocate removes an element from the
- * pool, and \c Free returns an element to the pool. It is only allowed to
- * free elements that have previously been allocated.
+ * A value pool is a multi-set of elements, where each element has a unique,
+ * continuous (starting with 0) index. The elements cannot be modified and are
+ * given at construction time by providing first/last iterators.
+ *
+ * \par
+ * A value pool provides two primary operations: \c Allocate and \c Free. \c
+ * Allocate allocates an element/index "pair" (index via return, element via
+ * reference parameter) from the pool, and \c Free returns an element/index pair
+ * to the pool. To guarantee linearizability, \c element is not allowed to be
+ * modified between \c Allocate and \c Free. It is only allowed to free elements
+ * that have previously been allocated. The \c Allocate function does not
+ * guarantee an order on which indices are allocated. The count of elements that
+ * can be allocated with \c Allocate might be smaller than the count of
+ * elements, the pool is initialized with. This might be because of
+ * implementation details and respective concurrency effects: for example, if
+ * indices are managed within a queue, one has to protect queue elements from
+ * concurrency effects (reuse and access). As long as a thread potentially
+ * accesses a node (and with that an index), the respective index cannot not be
+ * given out to the user, even if being logically not part of the pool anymore.
+ * However, the user might want to guarantee a certain amount of indices to the
+ * user. Therefore, the static \c GetMinimumElementCountForGuaranteedCapacity
+ * method is used. The user passes the count of indices to this method, that
+ * shall be guaranteed by the pool. The method returns the count on indices, the
+ * pool has to be initialized with in order to guarantee this count on indices.
  *
  * \par Requirements
  * - Let \c Pool be the pool class
@@ -54,6 +72,7 @@ namespace containers {
  * - Let \c i, j be forward iterators supporting \c std::distance.
  * - Let \c c be an object of type \c Type&
  * - Let \c e be a value of type \c int
+ * - Let \c f be a value of type \c int
  *
  * \par Valid Expressions
  *
@@ -72,7 +91,7 @@ namespace containers {
  *     the bottom element. The bottom element cannot be stored in the pool, it
  *     is exclusively used to mark empty cells. The pool initially contains
  *     \c std::distance(i, j) elements which are copied during construction from
- *     the range \c [i, j). A concrete class satisfying the value pool concept
+ *     the range \c [i, j]. A concrete class satisfying the value pool concept
  *     might provide additional template parameters for specifying allocators.
  *     </td>
  *   </tr>
@@ -80,9 +99,10 @@ namespace containers {
  *     <td>\code{.cpp} Allocate(c) \endcode</td>
  *     <td>\c int</td>
  *     <td>
- *     Gets an element from the pool. Returns -1, if no element is available,
- *     i.e., the pool is empty. Otherwise, returns the index of the element in
- *     the pool. The value of the pool element is written into reference \c c.
+ *     Allocates an element/index "pair" from the pool. Returns -1, if no
+ *     element is available, i.e., the pool is empty. Otherwise, returns the
+ *     index of the element in the pool. The value of the pool element is
+ *     written into parameter reference \c c.
  *     </td>
  *   </tr>
  *   <tr>
@@ -93,6 +113,15 @@ namespace containers {
  *     \c Allocate. For each allocated element, \c Free must be called exactly
  *     once.</td>
  *   </tr>
+ *   <tr>
+ *     <td>\code{.cpp} GetMinimumElementCountForGuaranteedCapacity(f)
+ *     \endcode</td>
+ *     <td>\c void</td>
+ *     <td>Static method, returns the count of indices, the user has to
+ *     initialize the pool with in order to guarantee a count of \c f elements
+ *     (irrespective of concurrency effects).
+ *      </td>
+ *   </tr>
  * </table>
  *
  * \}
@@ -154,8 +183,12 @@ class WaitFreeArrayValuePool {
    * by it. However, usually one wants to guarantee a minimal capacity. The
    * count of elements, that must be given to the pool when to guarantee \c
    * capacity elements is computed using this function.
+   *
+   * \return count of indices the pool has to be initialized with
    */
-  static size_t GetMinimumElementCountForGuaranteedCapacity(size_t capacity);
+  static size_t GetMinimumElementCountForGuaranteedCapacity(
+    size_t capacity
+    /**< [IN] count of indices that shall be guaranteed */);
 
   /**
    * Destructs the pool.