diff --git a/cpu/cc2538/dev/gpio.h b/cpu/cc2538/dev/gpio.h
index 8a61f668b..3f93633a1 100644
--- a/cpu/cc2538/dev/gpio.h
+++ b/cpu/cc2538/dev/gpio.h
@@ -117,6 +117,20 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin);
 /** \brief Set pins with PIN_MASK of port with PORT_BASE to value.
  * \param PORT_BASE GPIO Port register offset
  * \param PIN_MASK Pin number mask. Pin 0: 0x01, Pin 1: 0x02 ... Pin 7: 0x80
+ * \param value The new value to write to the register. Only pins specified
+ *              by PIN_MASK will be set.
+ *
+ * \note The outcome of this macro invocation will be to write to the register
+ * a new value for multiple pins. For that reason, the value argument cannot be
+ * a simple 0 or 1. Instead, it must be the value corresponding to the pins that
+ * you wish to set.
+ *
+ * Thus, if you only want to set a single pin (e.g. pin 2), do \e not pass 1,
+ * but you must pass 0x04 instead (1 << 2). This may seem counter-intuitive at
+ * first glance, but it allows a single invocation of this macro to set
+ * multiple pins in one go if so desired. For example, you can set pins 3 and 1
+ * and the same time clear pins 2 and 0. To do so, pass 0x0F as the PIN_MASK
+ * and then use 0x0A as the value ((1 << 3) | (1 << 1) for pins 3 and 1)
  */
 #define GPIO_WRITE_PIN(PORT_BASE, PIN_MASK, value) \
   do { REG(((PORT_BASE) | GPIO_DATA) + ((PIN_MASK) << 2)) = (value); } while(0)
@@ -124,6 +138,12 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin);
 /** \brief Read pins with PIN_MASK of port with PORT_BASE.
  * \param PORT_BASE GPIO Port register offset
  * \param PIN_MASK Pin number mask. Pin 0: 0x01, Pin 1: 0x02 ... Pin 7: 0x80
+ * \return The value of the pins specified by PIN_MASK
+ *
+ * This macro will \e not return 0 or 1. Instead, it will return the values of
+ * the pins specified by PIN_MASK ORd together. Thus, if you pass 0xC3
+ * (0x80 | 0x40 | 0x02 | 0x01) as the PIN_MASK and pins 7 and 0 are high,
+ * the macro will return 0x81.
  */
 #define GPIO_READ_PIN(PORT_BASE, PIN_MASK) \
   REG(((PORT_BASE) | GPIO_DATA) + ((PIN_MASK) << 2))
@@ -261,7 +281,7 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin);
 
 /**
  * \brief Converts a pin number to a pin mask
- * \param The pin number in the range [0..7]
+ * \param PIN The pin number in the range [0..7]
  * \return A pin mask which can be used as the PIN_MASK argument of the macros
  * in this category
  */
@@ -269,7 +289,7 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin);
 
 /**
  * \brief Converts a port number to the port base address
- * \param The port number in the range 0 - 3. Likely GPIO_X_NUM.
+ * \param PORT The port number in the range 0 - 3. Likely GPIO_X_NUM.
  * \return The base address for the registers corresponding to that port
  * number.
  */