From e135bdc26647890ce179d6ff6bb3311e54b7d656 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ren=C3=A9=20Kijewski?= <rene.kijewski@fu-berlin.de>
Date: Sun, 18 May 2014 17:03:06 +0200
Subject: [PATCH] documentation: fix doxygen for `pthread_*.h`

The pthread header files aren't in the doxygen page anymore after #1137,
because I `@file`'d the `.c` files, not the `.h` files.

This change moves doxygen boilerplate.

Closes #1199.
---
 sys/posix/pthread/include/pthread.h           | 21 ++++++++++----
 sys/posix/pthread/include/pthread_barrier.h   | 13 +++++++++
 .../pthread/include/pthread_cancellation.h    | 14 +++++++++
 sys/posix/pthread/include/pthread_cleanup.h   | 14 +++++++--
 sys/posix/pthread/include/pthread_cond.h      | 12 +++-----
 sys/posix/pthread/include/pthread_mutex.h     | 13 +++++++++
 .../pthread/include/pthread_mutex_attr.h      | 29 +++++++++++++++----
 sys/posix/pthread/include/pthread_once.h      | 15 +++++++++-
 sys/posix/pthread/include/pthread_rwlock.h    | 13 +++++++++
 .../pthread/include/pthread_rwlock_attr.h     | 13 +++++++++
 .../pthread/include/pthread_scheduling.h      | 14 +++++++++
 sys/posix/pthread/include/pthread_spin.h      | 16 ++++++++++
 sys/posix/pthread/include/pthread_threading.h | 13 +++++++++
 .../pthread/include/pthread_threading_attr.h  | 13 +++++++++
 14 files changed, 190 insertions(+), 23 deletions(-)

diff --git a/sys/posix/pthread/include/pthread.h b/sys/posix/pthread/include/pthread.h
index 1c0eee6d03..b440ead6b0 100644
--- a/sys/posix/pthread/include/pthread.h
+++ b/sys/posix/pthread/include/pthread.h
@@ -1,10 +1,17 @@
-#ifndef RIOT_PTHREAD_H
-#define RIOT_PTHREAD_H	1
-
 /**
- * @ingroup pthread
+ * @defgroup pthread POSIX threads
+ * POSIX conforming multi-threading features.
+ * @ingroup posix
+ * @{
+ * @file
+ * @brief   POSIX conforming multi-threading features.
+ * @details Please see the transcluded `pthread_*.h` files for further information.
+ * @see     [The Open Group Base Specifications Issue 7: pthread.h - threads](http://pubs.opengroup.org/onlinepubs/9699919799/basedefs/pthread.h.html)
  */
 
+#ifndef __SYS__POSIX__PTHREAD__H
+#define __SYS__POSIX__PTHREAD__H
+
 #include <time.h>
 
 #include "kernel.h"
@@ -25,4 +32,8 @@
 #include "pthread_cancellation.h"
 #include "pthread_cond.h"
 
-#endif	/* pthread.h */
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_barrier.h b/sys/posix/pthread/include/pthread_barrier.h
index 1225f67da8..c9b5a0c325 100644
--- a/sys/posix/pthread/include/pthread_barrier.h
+++ b/sys/posix/pthread/include/pthread_barrier.h
@@ -1,7 +1,14 @@
 /**
  * @ingroup pthread
+ * @{
+ * @file
+ * @brief   Synchronization barriers.
+ * @note    Do not include this header file directly, but pthread.h.
  */
 
+#ifndef __SYS__POSIX__PTHREAD_BARRIER__H
+#define __SYS__POSIX__PTHREAD_BARRIER__H
+
 #include "mutex.h"
 
 /**
@@ -112,3 +119,9 @@ int pthread_barrierattr_getpshared(const pthread_barrierattr_t *attr, int *pshar
  * @returns   0, the invocation cannot fail
  */
 int pthread_barrierattr_setpshared(pthread_barrierattr_t *attr, int pshared);
+
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_cancellation.h b/sys/posix/pthread/include/pthread_cancellation.h
index ef66da2599..c85a91c564 100644
--- a/sys/posix/pthread/include/pthread_cancellation.h
+++ b/sys/posix/pthread/include/pthread_cancellation.h
@@ -1,7 +1,15 @@
 /**
  * @ingroup pthread
+ * @{
+ * @file
+ * @brief   Thread cancellation features.
+ * @note    None of these functions are implemented, yet.
+ * @note    Do not include this header file directly, but pthread.h.
  */
 
+#ifndef __SYS__POSIX__PTHREAD_CANCELLCATION__H
+#define __SYS__POSIX__PTHREAD_CANCELLCATION__H
+
 #define PTHREAD_CANCEL_DISABLE 0
 #define PTHREAD_CANCEL_ENABLE  1
 
@@ -41,3 +49,9 @@ int pthread_cancel(pthread_t th);
  * @details      If pthread_cancel() called before, the current thread exits with with the code #PTHREAD_CANCELED.
  */
 void pthread_testcancel(void);
+
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_cleanup.h b/sys/posix/pthread/include/pthread_cleanup.h
index d0dfd0d57e..c9f6c9f188 100644
--- a/sys/posix/pthread/include/pthread_cleanup.h
+++ b/sys/posix/pthread/include/pthread_cleanup.h
@@ -2,11 +2,13 @@
  * @ingroup pthread
  * @{
  * @file
- * @brief Cleanup primitives for pthread threads.
- * @author René Kijewski <kijewski@inf.fu-berlin.de>
- * @}
+ * @brief   Cleanup primitives for pthread threads.
+ * @note    Do not include this header file directly, but pthread.h.
  */
 
+#ifndef __SYS__POSIX__PTHREAD_CLEANUP__H
+#define __SYS__POSIX__PTHREAD_CLEANUP__H
+
 /**
  * @brief   Internal structure for pthread_cleanup_push()
  */
@@ -76,3 +78,9 @@ void __pthread_cleanup_pop(__pthread_cleanup_datum_t *datum, int execute);
         } while (0); \
         __pthread_cleanup_pop(&____datum__, ____execute__); \
     } while (0)
+
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_cond.h b/sys/posix/pthread/include/pthread_cond.h
index a829d6e630..5e22a4be35 100644
--- a/sys/posix/pthread/include/pthread_cond.h
+++ b/sys/posix/pthread/include/pthread_cond.h
@@ -7,19 +7,15 @@
  */
 
 /**
- * @defgroup
- * @brief
- * @ingroup     sys
+ * @ingroup pthread
  * @{
- *
- * @file        condition_variable.h
+ * @file
  * @brief       RIOT POSIX condition variable API
- *
  * @author      Martin Landsmann <martin.landsmann@haw-hamburg.de>
  */
 
-#ifndef _CONDITION_VARIABLE_H
-#define _CONDITION_VARIABLE_H
+#ifndef __SYS__POSIX__PTHREAD_COND__H
+#define __SYS__POSIX__PTHREAD_COND__H
 
 #include <time.h>
 #include "mutex.h"
diff --git a/sys/posix/pthread/include/pthread_mutex.h b/sys/posix/pthread/include/pthread_mutex.h
index fff0e36d02..4b982d48cf 100644
--- a/sys/posix/pthread/include/pthread_mutex.h
+++ b/sys/posix/pthread/include/pthread_mutex.h
@@ -1,7 +1,14 @@
 /**
  * @ingroup pthread
+ * @{
+ * @file
+ * @brief   Mutual exclusion.
+ * @note    Do not include this header file directly, but pthread.h.
  */
 
+#ifndef __SYS__POSIX__PTHREAD_MUTEX__H
+#define __SYS__POSIX__PTHREAD_MUTEX__H
+
 #include <time.h>
 
 #include "kernel.h"
@@ -89,3 +96,9 @@ int pthread_mutex_getprioceiling(const pthread_mutex_t *mutex, int *prioceiling)
  * @return          Well ... you'll get a link time error, so nothing will be returned.
  */
 int pthread_mutex_setprioceiling(pthread_mutex_t *mutex, int prioceiling, int *old_ceiling);
+
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_mutex_attr.h b/sys/posix/pthread/include/pthread_mutex_attr.h
index 957b83db82..4bdd03b3ad 100644
--- a/sys/posix/pthread/include/pthread_mutex_attr.h
+++ b/sys/posix/pthread/include/pthread_mutex_attr.h
@@ -1,3 +1,14 @@
+/**
+ * @ingroup pthread
+ * @{
+ * @file
+ * @brief   Attributes for pthread mutexes.
+ * @note    Do not include this header file directly, but pthread.h.
+ */
+
+#ifndef __SYS__POSIX__PTHREAD_MUTEX_ATTR__H
+#define __SYS__POSIX__PTHREAD_MUTEX_ATTR__H
+
 #include <errno.h>
 
 /**
@@ -14,18 +25,18 @@
  * @brief           A mutex that fails with `EDEADLK` if recursive locking was detected.
  * @note            Not implemented, yet.
  */
-#define PTHREAD_MUTEX_NORMAL     0
-#define PTHREAD_MUTEX_RECURSIVE  1
-#define PTHREAD_MUTEX_ERRORCHECK 2
-#define PTHREAD_MUTEX_DEFAULT    PTHREAD_MUTEX_NORMAL
-
 /**
  * @def             PTHREAD_MUTEX_DEFAULT
  * @brief           The default mutex kind for RIOT.
  * @note            Not implemented, yet.
  */
+#define PTHREAD_MUTEX_NORMAL     0
+#define PTHREAD_MUTEX_RECURSIVE  1
+#define PTHREAD_MUTEX_ERRORCHECK 2
+#define PTHREAD_MUTEX_DEFAULT    PTHREAD_MUTEX_NORMAL
+
 /**
- * @def             PTHREAD_MUTEX_DEFAULT
+ * @def             PTHREAD_PRIO_NONE
  * @brief           No priority inheritance.
  * @details         Prone to inversed priorities.
  *                  The default mutex protocol.
@@ -187,3 +198,9 @@ int pthread_mutexattr_getrobust(const pthread_mutexattr_t *attr, int *robustness
  *                  `EINVAL` if `attr == NULL`.
  */
 int pthread_mutexattr_setrobust(pthread_mutexattr_t *attr, int robustness);
+
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_once.h b/sys/posix/pthread/include/pthread_once.h
index 02e2495ec1..e5e399f2a8 100644
--- a/sys/posix/pthread/include/pthread_once.h
+++ b/sys/posix/pthread/include/pthread_once.h
@@ -1,7 +1,14 @@
 /**
  * @ingroup pthread
+ * @{
+ * @file
+ * @brief   Singletons features / single-shot execution.
+ * @note    Do not include this header file directly, but pthread.h.
  */
 
+#ifndef __SYS__POSIX__PTHREAD_ONCE__H
+#define __SYS__POSIX__PTHREAD_ONCE__H
+
 /**
  * @brief           Datatype to supply to pthread_once().
  */
@@ -18,9 +25,15 @@ typedef volatile int pthread_once_t;
  * @brief           Helper function that ensures that `init_routine` is called at once.
  * @details         Calling pthread_once() changes `once_control`.
  *                  For the same `once_control` the supplied `init_routine` won't get called again,
- *                  unless `once_control` is reset to `PTHREAD_ONCE_INIT` or zeroed out.
+ *                  unless `once_control` is reset to #PTHREAD_ONCE_INIT or zeroed out.
  * @param[in,out]   once_control   Flag to ensure that the `init_routine` is called only once.
  * @param[in]       init_routine   Function to call if `once_control` was not used, yet.
  * @returns         0, this invocation cannot fail.
  */
 int pthread_once(pthread_once_t *once_control, void (*init_routine)(void));
+
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_rwlock.h b/sys/posix/pthread/include/pthread_rwlock.h
index b5b5b77219..fefa63066a 100644
--- a/sys/posix/pthread/include/pthread_rwlock.h
+++ b/sys/posix/pthread/include/pthread_rwlock.h
@@ -1,7 +1,14 @@
 /**
  * @ingroup pthread
+ * @{
+ * @file
+ * @brief   Implementation of a fair, POSIX conforming reader/writer lock.
+ * @note    Do not include this header file directly, but pthread.h.
  */
 
+#ifndef __SYS__POSIX__PTHREAD_RWLOCK__H
+#define __SYS__POSIX__PTHREAD_RWLOCK__H
+
 #include "queue.h"
 #include "tcb.h"
 
@@ -153,3 +160,9 @@ bool __pthread_rwlock_blocked_readingly(const pthread_rwlock_t *rwlock);
  * @returns          `false` if locking for writing is possible without blocking.
  */
 bool __pthread_rwlock_blocked_writingly(const pthread_rwlock_t *rwlock);
+
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_rwlock_attr.h b/sys/posix/pthread/include/pthread_rwlock_attr.h
index 3e895b6c89..05c1d9ce44 100644
--- a/sys/posix/pthread/include/pthread_rwlock_attr.h
+++ b/sys/posix/pthread/include/pthread_rwlock_attr.h
@@ -1,7 +1,14 @@
 /**
  * @ingroup pthread
+ * @{
+ * @file
+ * @brief   Implementation of a fair, POSIX conforming reader/writer lock (attribute set).
+ * @note    Do not include this header file directly, but pthread.h.
  */
 
+#ifndef __SYS__POSIX__PTHREAD_RWLOCK_ATTR__H
+#define __SYS__POSIX__PTHREAD_RWLOCK_ATTR__H
+
 #include <errno.h>
 
 /**
@@ -56,3 +63,9 @@ int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *attr, int *pshared
  *                  `EINVAL` if `attr == NULL` or a wrong value for `pshared` was supplied.
  */
 int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, int pshared);
+
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_scheduling.h b/sys/posix/pthread/include/pthread_scheduling.h
index 1ab0d9f811..a0694f5bc5 100644
--- a/sys/posix/pthread/include/pthread_scheduling.h
+++ b/sys/posix/pthread/include/pthread_scheduling.h
@@ -1,7 +1,15 @@
 /**
  * @ingroup pthread
+ * @{
+ * @file
+ * @brief   Scheduling parameters and policies of pthreads.
+ * @note    None of these functions are implemented, yet.
+ * @note    Do not include this header file directly, but pthread.h.
  */
 
+#ifndef __SYS__POSIX__PTHREAD_SCHEDULING__H
+#define __SYS__POSIX__PTHREAD_SCHEDULING__H
+
 /**
  * @brief           Unimplemented.
  * @note            Due to the native of RIOT it is unlikely that this function will ever be implemented.
@@ -30,3 +38,9 @@ int pthread_getschedparam(pthread_t target_thread, int *policy, struct sched_par
  * @returns         The function is unimplemented. Using it will cause a link time error.
  */
 int pthread_setschedprio(pthread_t target_thread, int prio);
+
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_spin.h b/sys/posix/pthread/include/pthread_spin.h
index 0a5bb62d9c..9d6b30eac3 100644
--- a/sys/posix/pthread/include/pthread_spin.h
+++ b/sys/posix/pthread/include/pthread_spin.h
@@ -1,7 +1,17 @@
 /**
  * @ingroup pthread
+ * @{
+ * @file
+ * @brief   Spin locks.
+ * @note    Do not include this header file directly, but pthread.h.
+ * @warning Spinlocks should be avoided.
+ *          They will burn away the battery needlessly, and may not work because RIOT is tickless.
+ *          Use disableIRQ() and restoreIRQ() for shortterm locks instead.
  */
 
+#ifndef __SYS__POSIX__PTHREAD_SPIN__H
+#define __SYS__POSIX__PTHREAD_SPIN__H
+
 #include <errno.h>
 
 /**
@@ -62,3 +72,9 @@ int pthread_spin_trylock(pthread_spinlock_t *lock);
  *                  `EINVAL` if `lock == NULL`.
  */
 int pthread_spin_unlock(pthread_spinlock_t *lock);
+
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_threading.h b/sys/posix/pthread/include/pthread_threading.h
index c77148fdbe..1d8d57928c 100644
--- a/sys/posix/pthread/include/pthread_threading.h
+++ b/sys/posix/pthread/include/pthread_threading.h
@@ -1,7 +1,14 @@
 /**
  * @ingroup pthread
+ * @{
+ * @file
+ * @brief   Thread creation features.
+ * @note    Do not include this header file directly, but pthread.h.
  */
 
+#ifndef __SYS__POSIX__PTHREAD_THREADING__H
+#define __SYS__POSIX__PTHREAD_THREADING__H
+
 #include "attributes.h"
 
 /**
@@ -83,3 +90,9 @@ static inline int pthread_equal(pthread_t thread1, pthread_t thread2)
 {
     return thread1 == thread2;
 }
+
+#endif
+
+/**
+ * @}
+ */
diff --git a/sys/posix/pthread/include/pthread_threading_attr.h b/sys/posix/pthread/include/pthread_threading_attr.h
index 133808ad9f..82dbe3b796 100644
--- a/sys/posix/pthread/include/pthread_threading_attr.h
+++ b/sys/posix/pthread/include/pthread_threading_attr.h
@@ -1,7 +1,14 @@
 /**
  * @ingroup pthread
+ * @{
+ * @file
+ * @brief   Thread creation features (attributes).
+ * @note    Do not include this header file directly, but pthread.h.
  */
 
+#ifndef __SYS__POSIX__PTHREAD_THREADING_ATTR__H
+#define __SYS__POSIX__PTHREAD_THREADING_ATTR__H
+
 /**
  * @brief     An attribute set to supply to pthread_create()
  * @details   A zeroed out datum is default initiliazed.
@@ -181,3 +188,9 @@ int pthread_attr_getstacksize(const pthread_attr_t *attr, size_t *stacksize);
  * @return          0, this invocation cannot fail.
  */
 int pthread_attr_setstacksize(pthread_attr_t *attr, size_t stacksize);
+
+#endif
+
+/**
+ * @}
+ */
-- 
GitLab