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

@@ -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
+
+/**
+ * @}
+ */

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
+
+/**
+ * @}
+ */

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
+
+/**
+ * @}
+ */

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
+
+/**
+ * @}
+ */

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"

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
+
+/**
+ * @}
+ */

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.
  */
+/**
+ * @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
- * @brief           The default mutex kind for RIOT.
- * @note            Not implemented, yet.
- */
-/**
- * @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
+
+/**
+ * @}
+ */

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
+
+/**
+ * @}
+ */

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
+
+/**
+ * @}
+ */

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
+
+/**
+ * @}
+ */

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
+
+/**
+ * @}
+ */

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
+
+/**
+ * @}
+ */

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
+
+/**
+ * @}
+ */

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
+
+/**
+ * @}
+ */