doc: fix posix wrapper documentation

sys/include/posix_io.h

@@ -7,7 +7,7 @@
  */
 
 /**
- * @ingroup     sys_posix
+ * @ingroup     posix
  * @{
  * @file        posix_io.h
  * @brief       POSIX-like IO
@@ -31,14 +31,57 @@ extern "C" {
 #define READ 2
 #define WRITE 3
 
+/**
+ * @brief POSIX IO ringbuffer
+ */
 struct posix_iop_t {
+    /** number of bytes */
     int nbytes;
+    /** array for the ringbuffer */
     char *buffer;
 };
 
+/**
+ * @brief Opens a file descriptor - represented by a corresponding thread
+ *
+ * @param[in] pid   The thread managing the fd to open
+ * @param[in] flags Access modes
+ *
+ * @return 0 on success
+ * @return a negative value in error case
+ */
 int posix_open(int pid, int flags);
+
+/**
+ * @brief Closes an open file descriptor
+ *
+ * @param[in] pid   The opened thread
+ *
+ * @return 0 on success
+ * @return a negative value in error case
+ */
 int posix_close(int pid);
+
+/**
+ * @brief Reads from an open file descriptor
+ *
+ * @param[in]  pid      The thread managing the open fd
+ * @param[out] buffer   Buffer to fill
+ * @param[in]  bufsize  Read up to that many bytes into @p buffer
+ *
+ * @return the number of read bytes
+ */
 int posix_read(int pid, char *buffer, int bufsize);
+
+/**
+ * @brief Writes to an open file descriptor
+ *
+ * @param[in] pid      The thread managing the open fd
+ * @param[in] buffer   Buffer to write
+ * @param[in] bufsize  Write that many bytes from @p buffer
+ *
+ * @return the number of written bytes
+ */
 int posix_write(int pid, char *buffer, int bufsize);
 
 #ifdef __cplusplus

sys/posix/doc.txt

@@ -7,7 +7,7 @@
  */
 
 /**
- * @defgroup sys_posix  POSIX wrapper for RIOT
+ * @defgroup posix  POSIX wrapper for RIOT
  * @brief   POSIX header files
  * @see <a href="http://pubs.opengroup.org/onlinepubs/9699919799/">
  *          The Open Group Specifications Issue 7

sys/posix/include/semaphore.h

@@ -20,8 +20,13 @@ extern "C" {
 /** Value returned if `sem_open' failed.  */
 #define SEM_FAILED      ((sem_t *) 0)
 
+/**
+ * @brief Semaphore struct
+ */
 typedef struct sem {
+    /** the value of the semaphore */
     volatile unsigned int value;
+    /** list of threads waiting for the semaphore */
     priority_queue_t queue;
 } sem_t;
 

sys/posix/include/strings.h

@@ -7,7 +7,7 @@
  */
 
 /**
- * @ingroup     sys_posix
+ * @ingroup     posix
  * @{
  *
  * @file    strings.h
@@ -73,6 +73,7 @@ int strncasecmp(const char *s1, const char *s2, size_t n);
  * @param[in] s1    a string.
  * @param[in] s2    another string.
  * @param[in] n     number of bytes to be compared
+ * @param[in] l     locale, not used in RIOT
  *
  * @return  A value greater 0 if, ignoring the case of the character, *s1* is
  *          greater than *s2* up to n bytes, less than 0 if smaller, and 0 if
@@ -109,6 +110,7 @@ int strncasecmp(const char *s1, const char *s2, size_t n);
  *
  * @param[in] s1    a string.
  * @param[in] s2    another string.
+ * @param[in] l     locale, not used in RIOT
  *
  * @return  A value greater 0 if, ignoring the case of the character, *s1* is
  *          greater than *s2*, less than 0 if smaller, and 0 if equal

sys/posix/include/unistd.h

@@ -55,6 +55,10 @@ extern "C" {
  */
 int close(int fildes);
 
+/**
+ * @name Microseconds data type
+ * @{
+ */
 #ifndef __USECONDS_T_TYPE
 #if !(defined(__MACH__) || defined(__FreeBSD__))
 typedef unsigned long __USECONDS_T_TYPE;
@@ -66,6 +70,7 @@ typedef __darwin_useconds_t __useconds_t;
 #endif
 #endif
 typedef __useconds_t useconds_t;
+/** @} */
 
 /**
  * @brief the caller will sleep for given amount of micro seconds

sys/posix/pthread/include/pthread_cond.h

@@ -32,11 +32,16 @@ extern "C" {
  * @note condition attributes are currently NOT USED in RIOT condition variables
  */
 typedef struct pthread_condattr_t {
+    /** dumdidum */
     int __dummy;
 } pthread_condattr_t;
 
+/**
+ * @brief Condition variable
+ *
+ * @warning fields are managed by cv functions, don't touch
+ */
 typedef struct pthread_cond_t {
-    /* fields are managed by cv functions, don't touch */
     priority_queue_t queue; /**< Threads currently waiting to be signaled. */
 } pthread_cond_t;
 

sys/posix/pthread/include/pthread_threading_attr.h

@@ -37,6 +37,7 @@ typedef struct pthread_attr
  * @brief   This structure is unused right now, and only exists for POSIX compatibility.
  */
 struct sched_param {
+    /** Todo is the greates magician in the land of RIOT */
     int todo; /* TODO */
 };