Merge pull request #6003 from miri64/core/doc/msg-init-queue-power-of-two

doc: make the 2^x requirement for msg_queue more visible

core/include/msg.h

@@ -98,11 +98,11 @@
  * Asynchronous IPC
  * ----------------
  * To use asynchronous IPC one needs to initialize a message queue using
- * @ref msg_init_queue(). Messages sent to a thread with a message queue that
- * isn't full are never dropped and the sending never blocks, even when using
- * @ref msg_send(). If the queue is full and the sending thread has a higher
- * priority than the receiving thread the send-behavior is equivalent to
- * synchronous mode.
+ * @ref msg_init_queue() (note that it **must** be of a size equal to a power of
+ * two). Messages sent to a thread with a message queue that isn't full are
+ * never dropped and the sending never blocks, even when using @ref msg_send().
+ * If the queue is full and the sending thread has a higher priority than the
+ * receiving thread the send-behavior is equivalent to synchronous mode.
  *
  * ~~~~~~~~~~~~~~~~~~~~~~~~ {.c}
  * #include <inttypes.h>
@@ -365,6 +365,8 @@ int msg_avail(void);
 /**
  * @brief Initialize the current thread's message queue.
  *
+ * @pre @p num **MUST BE A POWER OF TWO!**
+ *
  * @param[in] array Pointer to preallocated array of ``msg_t`` structures, must
  *                  not be NULL.
  * @param[in] num   Number of ``msg_t`` structures in array.

sys/include/net/gnrc.h

@@ -55,7 +55,8 @@
  * Hence, a thread for @ref net_gnrc "GNRC" will usually consist of four basic
  * steps.
  *
- * 1. Initialize a message queue
+ * 1. Initialize a message queue (note that its size **must** be a power of two,
+ *    see @ref msg_init_queue())
  * 2. register for a @ref net_gnrc_nettype
  * 3. wait for a message
  * 4. react appropriately to a message and return to 3.