Fix a bunch of Doxygen file-level comments.

Fix @file in many places. Also fix up the descriptions where it's
appropriate. This standardizes the @file formatting across the library
to explicitly include any parent directories up to the repository
root.

Besides being nice, this will hopefully let us manage Doxygen's XML
output so as to make extracting series-specific pieces via Breathe in
the leaflabs-docs repo possible.

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

16 files changed, 25 insertions, 23 deletions

diff --git a/libmaple/stm32f1/adc.c b/libmaple/stm32f1/adc.c
index 794c5c8..facc6bd 100644
--- a/libmaple/stm32f1/adc.c
+++ b/libmaple/stm32f1/adc.c
@@ -26,10 +26,10 @@
  *****************************************************************************/
 
 /**
- * @file libmaple/stm32f1/include/series/adc.c
+ * @file libmaple/stm32f1/adc.c
  * @author Marti Bolivar <mbolivar@leaflabs.com>,
  *         Perry Hung <perry@leaflabs.com>
- * @brief STM32F1-specific ADC support.
+ * @brief STM32F1 ADC support.
  */
 
 #include <libmaple/adc.h>
diff --git a/libmaple/stm32f1/bkp.c b/libmaple/stm32f1/bkp.c
index 62783e7..f435ff1 100644
--- a/libmaple/stm32f1/bkp.c
+++ b/libmaple/stm32f1/bkp.c
@@ -25,8 +25,8 @@
  *****************************************************************************/
 
 /**
- * @file bkp.c
- * @brief Backup register support.
+ * @file libmaple/stm32f1/bkp.c
+ * @brief STM32F1 Backup register support.
  */
 
 #include <libmaple/bkp.h>
diff --git a/libmaple/stm32f1/fsmc.c b/libmaple/stm32f1/fsmc.c
index 8e01b5e..210f0be 100644
--- a/libmaple/stm32f1/fsmc.c
+++ b/libmaple/stm32f1/fsmc.c
@@ -26,7 +26,7 @@
  *****************************************************************************/
 
 /**
- * @file stm32f1/fsmc.c
+ * @file libmaple/stm32f1/fsmc.c
  * @author Marti Bolivar <mbolivar@leaflabs.com>,
  *         Bryan Newbold <bnewbold@robocracy.org>
  * @brief STM32F1 FSMC support.
diff --git a/libmaple/stm32f1/gpio.c b/libmaple/stm32f1/gpio.c
index 01a4028..2cbe299 100644
--- a/libmaple/stm32f1/gpio.c
+++ b/libmaple/stm32f1/gpio.c
@@ -26,7 +26,7 @@
 
 /**
  * @file libmaple/stm32f1/gpio.c
- * @brief GPIO support for STM32F1 line.
+ * @brief STM32F1 GPIO support.
  */
 
 #include <libmaple/gpio.h>
diff --git a/libmaple/stm32f1/include/series/adc.h b/libmaple/stm32f1/include/series/adc.h
index 007641a..774c97c 100644
--- a/libmaple/stm32f1/include/series/adc.h
+++ b/libmaple/stm32f1/include/series/adc.h
@@ -26,7 +26,7 @@
  *****************************************************************************/
 
 /**
- * @file stm32f1/include/series/adc.h
+ * @file libmaple/stm32f1/include/series/adc.h
  * @author Marti Bolivar <mbolivar@leaflabs.com>,
  *         Perry Hung <perry@leaflabs.com>
  * @brief STM32F1 ADC header.
diff --git a/libmaple/stm32f1/include/series/flash.h b/libmaple/stm32f1/include/series/flash.h
index 5603176..0c70986 100644
--- a/libmaple/stm32f1/include/series/flash.h
+++ b/libmaple/stm32f1/include/series/flash.h
@@ -25,7 +25,7 @@
  *****************************************************************************/
 
 /**
- * @file libmaple/stm32f1/flash.h
+ * @file libmaple/stm32f1/include/series/flash.h
  * @brief STM32F1 Flash header.
  *
  * Provides register map, base pointer, and register bit definitions
diff --git a/libmaple/stm32f1/include/series/gpio.h b/libmaple/stm32f1/include/series/gpio.h
index c10244d..1f209fe 100644
--- a/libmaple/stm32f1/include/series/gpio.h
+++ b/libmaple/stm32f1/include/series/gpio.h
@@ -26,9 +26,11 @@
 *****************************************************************************/
 
 /**
- *  @file libmaple/stm32f1/gpio.h
- *  @brief General purpose I/O (GPIO) and Alternate Function I/O
- *         (AFIO) prototypes, defines, and inlined access functions.
+ * @file libmaple/stm32f1/include/series/gpio.h
+ * @brief STM32F1 GPIO support.
+ *
+ * General purpose I/O (GPIO) and Alternate Function I/O (AFIO)
+ * prototypes, defines, and support functions.
  */
 
 #ifndef _LIBMAPLE_STM32F1_GPIO_H_
diff --git a/libmaple/stm32f1/include/series/pwr.h b/libmaple/stm32f1/include/series/pwr.h
index d13ffa7..e143a8c 100644
--- a/libmaple/stm32f1/include/series/pwr.h
+++ b/libmaple/stm32f1/include/series/pwr.h
@@ -25,7 +25,7 @@
  *****************************************************************************/
 
 /**
- * @file stm32f1/pwr.h
+ * @file libmaple/stm32f1/include/series/pwr.h
  * @author Marti Bolivar <mbolivar@leaflabs.com>
  * @brief STM32F1 Power control (PWR) support.
  */
diff --git a/libmaple/stm32f1/include/series/rcc.h b/libmaple/stm32f1/include/series/rcc.h
index f60b07b..3e7f7c6 100644
--- a/libmaple/stm32f1/include/series/rcc.h
+++ b/libmaple/stm32f1/include/series/rcc.h
@@ -26,8 +26,8 @@
  *****************************************************************************/
 
 /**
- * @file libmaple/stm32f1/rcc.h
- * @brief STM32F1 reset and clock control (RCC) header.
+ * @file libmaple/stm32f1/include/series/rcc.h
+ * @brief STM32F1 reset and clock control (RCC) support.
  */
 
 #ifndef _LIBMAPLE_STM32F1_RCC_H_
diff --git a/libmaple/stm32f1/include/series/stm32.h b/libmaple/stm32f1/include/series/stm32.h
index 999abab..e6d3b19 100644
--- a/libmaple/stm32f1/include/series/stm32.h
+++ b/libmaple/stm32f1/include/series/stm32.h
@@ -25,7 +25,7 @@
  *****************************************************************************/
 
 /**
- * @file libmaple/stm32f1/stm32.h
+ * @file libmaple/stm32f1/include/series/stm32.h
  * @brief STM32F1 chip- and series-specific definitions.
  */
 
diff --git a/libmaple/stm32f1/include/series/timer.h b/libmaple/stm32f1/include/series/timer.h
index 2551f70..8a64ffa 100644
--- a/libmaple/stm32f1/include/series/timer.h
+++ b/libmaple/stm32f1/include/series/timer.h
@@ -25,9 +25,9 @@
  *****************************************************************************/
 
 /**
- * @file   stm32f1/include/series/timer.h
+ * @file   libmaple/stm32f1/include/series/timer.h
  * @author Marti Bolivar <mbolivar@leaflabs.com>
- * @brief  STM32F1 timer sub-header.
+ * @brief  STM32F1 timer support.
  */
 
 #ifndef _LIBMAPLE_STM32F1_TIMER_H_
diff --git a/libmaple/stm32f1/include/series/usart.h b/libmaple/stm32f1/include/series/usart.h
index 93a7728..d12a3e2 100644
--- a/libmaple/stm32f1/include/series/usart.h
+++ b/libmaple/stm32f1/include/series/usart.h
@@ -25,9 +25,9 @@
  *****************************************************************************/
 
 /**
- * @file libmaple/stm32f1/usart.h
+ * @file libmaple/stm32f1/include/series/usart.h
  * @author Marti Bolivar <mbolivar@leaflabs.com>
- * @brief STM32F1 USART header.
+ * @brief STM32F1 USART support.
  */
 
 #ifndef _LIBMAPLE_STM32F1_USART_H_
diff --git a/libmaple/stm32f1/rcc.c b/libmaple/stm32f1/rcc.c
index aeedf66..ca81755 100644
--- a/libmaple/stm32f1/rcc.c
+++ b/libmaple/stm32f1/rcc.c
@@ -27,7 +27,7 @@
 
 /**
  * @file libmaple/stm32f1/rcc.c
- * @brief STM32F1 RCC routines.
+ * @brief STM32F1 RCC.
  */
 
 #include <libmaple/rcc.h>
diff --git a/libmaple/stm32f1/spi.c b/libmaple/stm32f1/spi.c
index 45ff354..8b6e495 100644
--- a/libmaple/stm32f1/spi.c
+++ b/libmaple/stm32f1/spi.c
@@ -28,7 +28,7 @@
 /**
  * @file libmaple/stm32f1/spi.c
  * @author Marti Bolivar <mbolivar@leaflabs.com>
- * @brief STM32F1 SPI/I2S support.
+ * @brief STM32F1 SPI/I2S.
  */
 
 #include <libmaple/spi.h>
diff --git a/libmaple/stm32f1/timer.c b/libmaple/stm32f1/timer.c
index 899abbc..002b9d6 100644
--- a/libmaple/stm32f1/timer.c
+++ b/libmaple/stm32f1/timer.c
@@ -27,7 +27,7 @@
 /**
  * @file   libmaple/stm32f1/timer.c
  * @author Marti Bolivar <mbolivar@leaflabs.com>
- * @brief  STM32F1 timer support.
+ * @brief  STM32F1 timer.
  */
 
 /* Notes:
diff --git a/libmaple/stm32f1/usart.c b/libmaple/stm32f1/usart.c
index ee68082..eed420e 100644
--- a/libmaple/stm32f1/usart.c
+++ b/libmaple/stm32f1/usart.c
@@ -29,7 +29,7 @@
  * @file libmaple/stm32f1/usart.c
  * @author Marti Bolivar <mbolivar@leaflabs.com>,
  *         Perry Hung <perry@leaflabs.com>
- * @brief STM32F1 USART support.
+ * @brief STM32F1 USART.
  */
 
 #include <libmaple/usart.h>