Merge pull request #7901 from kroesche/feature/ringbuf_doc_update

ringbuffer: add hint about tsrb to doc

core/include/ringbuffer.h

@@ -1,18 +1,24 @@
-/**
- * Ringbuffer header
- *
+/*
  * Copyright (C) 2013 Freie Universität Berlin
  * Copyright (C) 2013 INRIA
  *
  * This file is subject to the terms and conditions of the GNU Lesser
  * General Public License v2.1. See the file LICENSE in the top level
  * directory for more details.
- *
+ */
+
+/**
  * @ingroup  core_util
  * @{
  * @file
  * @author Kaspar Schleiser <kaspar@schleiser.de>
  * @author René Kijewski <rene.kijewski@fu-berlin.de>
+ *
+ * @brief A utility for storing and retrieving byte data using a ring buffer.
+ *
+ * @details The ringbuffer is useful for buffering data in the same
+ * thread context but it is not thread-safe.  For a thread-safe ring
+ * buffer, see @ref sys_tsrb in the System library.
  * @}
  */
 

sys/include/tsrb.h

@@ -12,14 +12,14 @@
  * @brief       Thread-safe ringbuffer implementation
  * @{
  *
- * @file
- * @brief       Thread-safe ringbuffer interface definition
- *
  * @note        This ringbuffer implementation can be used without locking if
  *              there's only one producer and one consumer.
  *
  * @attention   Buffer size must be a power of two!
  *
+ * @file
+ * @brief       Thread-safe ringbuffer interface definition
+ *
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
  */
 
@@ -38,7 +38,7 @@ extern "C" {
  */
 typedef struct tsrb {
     char *buf;                  /**< Buffer to operate on. */
-    unsigned int size;          /**< Size of buf. */
+    unsigned int size;          /**< Size of buffer, must be power of 2. */
     volatile unsigned reads;    /**< total number of reads */
     volatile unsigned writes;   /**< total number of writes */
 } tsrb_t;
@@ -52,7 +52,7 @@ typedef struct tsrb {
  * @brief        Initialize a tsrb.
  * @param[out]   rb        Datum to initialize.
  * @param[in]    buffer    Buffer to use by tsrb.
- * @param[in]    bufsize   `sizeof (buffer)`
+ * @param[in]    bufsize   `sizeof (buffer)`, must be power of 2.
  */
 static inline void tsrb_init(tsrb_t *rb, char *buffer, unsigned bufsize)
 {