From 46cfbb24b3001c0cf5cf25e6cae05cc3a83617f3 Mon Sep 17 00:00:00 2001
From: Christian Kern <christian.kern@siemens.com>
Date: Wed, 4 Nov 2015 14:36:20 +0100
Subject: [PATCH] Add concept documentation

---
 base_cpp/include/embb/base/mutex.h | 84 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 71 insertions(+), 13 deletions(-)

diff --git a/base_cpp/include/embb/base/mutex.h b/base_cpp/include/embb/base/mutex.h
index a2b88ee..54c415e 100644
--- a/base_cpp/include/embb/base/mutex.h
+++ b/base_cpp/include/embb/base/mutex.h
@@ -34,6 +34,60 @@
 namespace embb {
 namespace base {
 /**
+ * \defgroup CPP_CONCEPTS_MUTEX Mutex Concept
+ *
+ * \brief Concept for thread synchronization.
+ *
+ * \anchor CPP_CONCEPTS_MUTEX_ANCHOR
+ *
+ * \ingroup CPP_CONCEPT
+ * \{
+ * \par Description
+ *
+ * The mutex concept is a concept for thread synchronization. It provides a
+ * lock. At any point in time, only one thread can exclusively hold the lock and
+ * the lock is held, until the thread explicitly releases the beforehand
+ * acquired lock.
+ *
+ * \par Requirements
+ * - Let \c Mutex be the mutex type
+ * - Let \c m be an object of type \c Mutex.
+ *
+ * \par Valid Expressions
+ *
+ * <table>
+ *   <tr>
+ *     <th>Expression</th>
+ *     <th>Return type</th>
+ *     <th>Description</th>
+ *   </tr>
+ *   <tr>
+ *     <td>Mutex()</td>
+ *     <td>\c void</td>
+ *     <td>Constructs a mutex.</td>
+ *   </tr>
+ *   <tr>
+ *     <td>m.TryLock()</td>
+ *     <td>\c bool</td>
+ *     <td>Tries to lock the mutex and immediately returns. Returns \c false, if
+ *     the mutex could not be acquired (locked), otherwise \c true.
+ *   </tr>
+ *   <tr>
+ *     <td>m.Lock()</td>
+ *     <td>\c void</td>
+ *     <td>Locks the mutex. When the mutex is already locked, the current thread
+ *     is blocked until the mutex is unlocked.</td>
+ *   </tr>
+ *   <tr>
+ *     <td>m.Unlock()</td>
+ *     <td>\c void</td>
+ *     <td>Unlocks the mutex.</td>
+ *   </tr>
+ * </table>
+ * \}
+ */
+
+/**
  * \defgroup CPP_BASE_MUTEX Mutex and Lock
  *
  * Mutexes and locks for thread synchronization.
@@ -113,17 +167,11 @@ class MutexBase {
 } // namespace internal
 
 /**
- * \defgroup CPP_BASE_SPINLOCK Spinlock
- *
- * Spinlock for thread synchronization.
- *
- * \ingroup CPP_BASE
- */
-
-/**
  * Spinlock
  *
- * \ingroup CPP_BASE_SPINLOCK
+ * \concept{CPP_CONCEPTS_MUTEX}
+ *
+ * \ingroup CPP_BASE_MUTEX
  */
 class Spinlock {
  public:
@@ -172,7 +220,10 @@ class Spinlock {
    * \threadsafe
    * \see Lock(), Unlock()
    */
-  bool TryLock(unsigned int number_spins = 1) {
+  bool TryLock(
+    unsigned int number_spins = 1
+    /**< [IN] Maximal spins to perform, trying to acquire lock */
+    ) {
     int status = embb_spin_try_lock(&spinlock_, number_spins);
 
     if (status == EMBB_BUSY){
@@ -223,6 +274,8 @@ class Spinlock {
  *
  * \see RecursiveMutex
  * \ingroup CPP_BASE_MUTEX
+ *
+ * \concept{CPP_CONCEPTS_MUTEX}
  */
 class Mutex : public internal::MutexBase {
  public:
@@ -292,6 +345,8 @@ class Mutex : public internal::MutexBase {
  *
  * \see Mutex
  * \ingroup CPP_BASE_MUTEX
+ *
+ * \concept{CPP_CONCEPTS_MUTEX}
  */
 class RecursiveMutex : public internal::MutexBase {
  public:
@@ -351,8 +406,10 @@ class RecursiveMutex : public internal::MutexBase {
  * The mutex is locked on construction and unlocked on leaving the scope of the
  * lock.
  *
- * \tparam Mutex Used mutex type
- * \see Mutex, UniqueLock
+ * \tparam Mutex Used mutex type. Has to fulfil the
+ *         \ref CPP_CONCEPTS_MUTEX_ANCHOR "Mutex Concept".
+ *
+ * \see UniqueLock
  * \ingroup CPP_BASE_MUTEX
  */
 template<typename Mutex = embb::base::Mutex>
@@ -450,7 +507,8 @@ const AdoptLockTag adopt_lock = AdoptLockTag();
  *
  * \notthreadsafe
  * \see Mutex, LockGuard
- * \tparam Mutex Used mutex type
+ * \tparam Mutex Used mutex type. Has to fulfil the
+ *         \ref CPP_CONCEPTS_MUTEX_ANCHOR "Mutex Concept".
  * \ingroup CPP_BASE_MUTEX
  */
 template<typename Mutex = embb::base::Mutex>
--
libgit2 0.26.0