sys/include/tsrb.h: move usage doc to main API page.

Modified file doc header so that important info about usage and buffer
size show up on main API doc page instead of file doc page;
added comment in a couple of places to remind reader that buffer size
must be powewr of 2.

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)
 {