diff --git a/os/common/oslib/include/chmboxes.h b/os/common/oslib/include/chmboxes.h
index 8dc38a374..e3c16c78d 100644
--- a/os/common/oslib/include/chmboxes.h
+++ b/os/common/oslib/include/chmboxes.h
@@ -72,8 +72,8 @@ typedef struct {
  *          mailbox that is part of a bigger structure.
  *
  * @param[in] name      the name of the mailbox variable
- * @param[in] buffer    pointer to the mailbox buffer area
- * @param[in] size      size of the mailbox buffer area
+ * @param[in] buffer    pointer to the mailbox buffer array of @p msg_t
+ * @param[in] size      number of @p msg_t elements in the buffer array
  */
 #define _MAILBOX_DATA(name, buffer, size) {                                 \
   (msg_t *)(buffer),                                                        \
@@ -89,11 +89,11 @@ typedef struct {
 /**
  * @brief   Static mailbox initializer.
  * @details Statically initialized mailboxes require no explicit
- *          initialization using @p chMBInit().
+ *          initialization using @p chMBObjectInit().
  *
  * @param[in] name      the name of the mailbox variable
- * @param[in] buffer    pointer to the mailbox buffer area
- * @param[in] size      size of the mailbox buffer area
+ * @param[in] buffer    pointer to the mailbox buffer array of @p msg_t
+ * @param[in] size      number of @p msg_t elements in the buffer array
  */
 #define MAILBOX_DECL(name, buffer, size)                                    \
   mailbox_t name = _MAILBOX_DATA(name, buffer, size)
diff --git a/readme.txt b/readme.txt
index 8b4754fd3..96b3d67d1 100644
--- a/readme.txt
+++ b/readme.txt
@@ -117,6 +117,8 @@
        Updated the various platform.mk implementing "smart build" mode.
 - HAL: Fixed USB GET_DESCRIPTOR not handled for Interface Recipients (bug #885)
        (backported to 17.6.1 and 16.1.9).
+- RT:  MAILBOX_DECL size parameter is actually a count (bug #884)
+       (backported to 17.6.1 and 16.1.9).
 - HAL: Fixed error in uartReceiveTimeout() and uartSendTimeout() (bug #883)
        (backported to 17.6.1 and 16.1.9).
 - HAL: Fixed TIMx DBL field macro broken (bug #880)(backported