drivers/periph/gpio(_ll): Enhance and fix the documentation

drivers/include/periph/gpio.h

@@ -96,7 +96,7 @@
  * @brief   Convert (port, pin) tuple to @c gpio_t value
  */
 /* Default GPIO macro maps port-pin tuples to the pin value */
 #define GPIO_PIN(x,y)       ((gpio_t)((x & 0) | y))
 #endif
 
 #ifndef GPIO_UNDEF
@@ -116,7 +116,7 @@
  */
 #ifndef HAVE_GPIO_MODE_T
 typedef enum {
     GPIO_IN ,               /**< configure as input without pull resistor */
     GPIO_IN_PD,             /**< configure as input with pull-down resistor */
     GPIO_IN_PU,             /**< configure as input with pull-up resistor */
     GPIO_OUT,               /**< configure as output in push-pull mode */
@@ -199,8 +199,8 @@
 /**
  * @brief   Enable pin interrupt if configured as interrupt source
  *
- *          Interrupts that would have occurred after @see gpio_irq_disable
- *          was called will be discarded.
+ * Interrupts that would have occurred after @see gpio_irq_disable
+ * was called will be discarded.
  *
  * @note    You have to add the module `periph_gpio_irq` to your project to
  *          enable this function

drivers/include/periph/gpio_ll.h

@@ -17,6 +17,15 @@
  * @warning     This API is not stable yet and intended for internal use only
  *              as of now.
  *
+ * # General
+ *
+ * Ports and pin numbers are not always internally defined as the same numbers
+ * that you would expect them to be. Therefore it is highly recommended to call
+ * the low level functions like gpio_ll_init() or gpio_ll_query_conf() with the
+ * gpio_get_port() and gpio_get_pin_num() functions instead of directly setting
+ * port or pin numbers. Using the helper functions will assure reliable
+ * operation on all platforms and GPIO banks.
+ *
  * # Design Goals
  *
  * This API aims to provide low-level access to GPIOs with as little
@@ -821,11 +830,31 @@ static inline void gpio_ll_write(gpio_port_t port, uword_t state);
 
 /**
  * @brief   Extract the `gpio_port_t` from a `gpio_t`
+ *
+ * CPU specific implementation to return the GPIO port for a given
+ * GPIO pin.
+ *
+ * @param[in] pin GPIO pin structure, usually defined with the GPIO_PIN macro
+ *
+ * @return  GPIO port
+ *
  */
 static inline gpio_port_t gpio_get_port(gpio_t pin);
 
 /**
  * @brief   Extract the pin number from a `gpio_t`
+ *
+ * CPU specific implementation to return the internal pin number for a
+ * given GPIO pin.
+ *
+ * @note    The actual, internal pin numbers are not always directly related to
+ *          their name. For example on some microcontrollers as the nRF52,
+ *          the distinction between P0 and P1 pins is made by a bit that is set
+ *          in the pin numbers.
+ *
+ * @param[in] pin GPIO pin structure, usually defined with the GPIO_PIN macro
+ *
+ * @return  Internal pin number
  */
 static inline uint8_t gpio_get_pin_num(gpio_t pin);