diff --git a/global.h b/global.h
index bf0b0fb..e02f41d 100644
--- a/global.h
+++ b/global.h
@@ -25,34 +25,40 @@
 /** get the length of an array */
 #define LENGTH(x) (sizeof(x) / sizeof((x)[0]))
 
-/* board LED GPIO */
+/** @defgroup board_led board LED GPIO
+ *  @{
+ */
 #if defined(SYSTEM_BOARD)
-/** on system board LED is on pin 11/PA1 */
-#define LED_RCC RCC_GPIOA 
-#define LED_PORT GPIOA
-#define LED_PIN	GPIO1
+/* on system board LED is on pin 11/PA1 */
+#define LED_RCC RCC_GPIOA /**< GPIO peripheral clock (port A on system board) */
+#define LED_PORT GPIOA /**< GPIO port (port A on system board) */
+#define LED_PIN	GPIO1 /**< GPIO pin (pin PA1 on system board) */
 #elif defined(BLUE_PILL)
-/** on minimum system LED is on pin 2/PC13 */
-#define LED_RCC RCC_GPIOC
-#define LED_PORT GPIOC
-#define LED_PIN GPIO13
+/* on minimum system LED is on pin 2/PC13 */
+#define LED_RCC RCC_GPIOC /**< GPIO peripheral clock (port C on blue pill) */
+#define LED_PORT GPIOC /**< GPIO port (port C on blue pill) */
+#define LED_PIN GPIO13 /**< GPIO pin (pin PC13 on system board) */
 #elif defined (MAPLE_MINI)
-/** on maple mini LED is on pin 19/PB1 */
-#define LED_RCC RCC_GPIOB
-#define LED_PORT GPIOB
-#define LED_PIN GPIO1
+/* on maple mini LED is on pin 19/PB1 */
+#define LED_RCC RCC_GPIOB /**< GPIO peripheral clock (port B on maple mini) */
+#define LED_PORT GPIOB /**< GPIO port (port B on maple mini) */
+#define LED_PIN GPIO1 /**< GPIO pin (pin PB1 on maple mini) */
 #endif
+/** @} */
 
-/* board user button GPIO */
+/** @defgroup board_button board user button GPIO
+ *  @{
+ */
 #if defined(MAPLE_MINI)
-/** on maple mini user button is on 32/PB8 */
-#define BUTTON_RCC RCC_GPIOB
-#define BUTTON_PORT GPIOB
-#define BUTTON_PIN GPIO8
-#define BUTTON_EXTI EXTI8
-#define BUTTON_IRQ NVIC_EXTI9_5_IRQ
-#define BUTTON_ISR exti9_5_isr
+/* on maple mini user button is on 32/PB8 */
+#define BUTTON_RCC RCC_GPIOB /**< GPIO peripheral clock (port B on maple mini) */
+#define BUTTON_PORT GPIOB /**< GPIO port (port B on maple mini) */
+#define BUTTON_PIN GPIO8 /**< GPIO pin (pin PB8 on maple mini) */
+#define BUTTON_EXTI EXTI8 /**< GPIO external interrupt (exti 8 for pin 8 on maple mini) */
+#define BUTTON_IRQ NVIC_EXTI9_5_IRQ /**< GPIO line interrupt (interrupt for line 9 to 5 for pin 8 on maple mini) */
+#define BUTTON_ISR exti9_5_isr /**< GPIO line interrupt service routine (isr for line 9 to 5 for pin 8 on maple mini) */
 #endif
+/** @} */
 
 /** @brief switch on board LED */
 void led_on(void);