doc: use common naming for peripheral apis

Only applied to STM32 doc trees at present. Instead of declaring a group for "STM32blah" in the doc-blah.h files, and then trying to put all the common+specific peripheral code into those groups, (which is what led to the stub doxygen holder empty .c files) Just use a standard name like "Peripheral APIS" and place everything into that. Demonstrated by converting ADC and USART peripherals, which is definitely not complete, but it shows how to make things less magical, and less prone to copy/paste errors. Now, you can copy/paste and it will do the right thing, because everyone uses the same group names. This is also how to unify the mix of "STM32blah->Periphblah" and _also_ the dangling "periph_file" modules in doxygen, it merges them together properly, as they're intended to be really.
7 years ago · b47b967440
21 changed files with 58 additions and 34 deletions
--- a/include/libopencm3/stm32/f0/doc-stm32f0.h
+++ b/include/libopencm3/stm32/f0/doc-stm32f0.h
@ -9,6 +9,10 @@
 * LGPL License Terms @ref lgpl_license
 */

+/** @defgroup peripheral_apis Peripheral APIs
+ * APIs for device peripherals
+ */
+
 /** @defgroup STM32F0xx STM32F0xx
 * Libraries for ST Microelectronics STM32F0xx series.
 *
--- a/include/libopencm3/stm32/f1/doc-stm32f1.h
+++ b/include/libopencm3/stm32/f1/doc-stm32f1.h
@ -9,6 +9,10 @@ API documentation for ST Microelectronics STM32F1 Cortex M3 series.
 LGPL License Terms @ref lgpl_license
 */

+/** @defgroup peripheral_apis Peripheral APIs
+ * APIs for device peripherals
+ */
+
 /** @defgroup STM32F1xx STM32F1xx
 Libraries for ST Microelectronics STM32F1xx series.

--- a/include/libopencm3/stm32/f2/doc-stm32f2.h
+++ b/include/libopencm3/stm32/f2/doc-stm32f2.h
@ -10,6 +10,10 @@ LGPL License Terms @ref lgpl_license
 */


+/** @defgroup peripheral_apis Peripheral APIs
+ * APIs for device peripherals
+ */
+
 /** @defgroup STM32F2xx STM32F2xx
 Libraries for ST Microelectronics STM32F2xx series.

--- a/include/libopencm3/stm32/f3/doc-stm32f3.h
+++ b/include/libopencm3/stm32/f3/doc-stm32f3.h
@ -9,6 +9,10 @@
 * LGPL License Terms @ref lgpl_license
 */

+/** @defgroup peripheral_apis Peripheral APIs
+ * APIs for device peripherals
+ */
+
 /** @defgroup STM32F3xx STM32F3xx
 * Libraries for ST Microelectronics STM32F3xx series.
 *
--- a/include/libopencm3/stm32/f4/doc-stm32f4.h
+++ b/include/libopencm3/stm32/f4/doc-stm32f4.h
@ -9,6 +9,10 @@ API documentation for ST Microelectronics STM32F4 Cortex M3 series.
 LGPL License Terms @ref lgpl_license
 */

+/** @defgroup peripheral_apis Peripheral APIs
+ * APIs for device peripherals
+ */
+
 /** @defgroup STM32F4xx STM32F4xx
 Libraries for ST Microelectronics STM32F4xx series.

--- a/include/libopencm3/stm32/f7/doc-stm32f7.h
+++ b/include/libopencm3/stm32/f7/doc-stm32f7.h
@ -9,6 +9,10 @@ API documentation for ST Microelectronics STM32F7 Cortex M7 series.
 LGPL License Terms @ref lgpl_license
 */

+/** @defgroup peripheral_apis Peripheral APIs
+ * APIs for device peripherals
+ */
+
 /** @defgroup STM32F7xx STM32F7xx
 Libraries for ST Microelectronics STM32F7xx series.

--- a/include/libopencm3/stm32/l0/doc-stm32l0.h
+++ b/include/libopencm3/stm32/l0/doc-stm32l0.h
@ -9,6 +9,10 @@ API documentation for ST Microelectronics STM32L0 Cortex M0 series.
 LGPL License Terms @ref lgpl_license
 */

+/** @defgroup peripheral_apis Peripheral APIs
+ * APIs for device peripherals
+ */
+
 /** @defgroup STM32L0xx STM32L0xx
 Libraries for ST Microelectronics STM32L0xx series.

--- a/include/libopencm3/stm32/l1/doc-stm32l1.h
+++ b/include/libopencm3/stm32/l1/doc-stm32l1.h
@ -9,6 +9,10 @@ API documentation for ST Microelectronics STM32L1 Cortex M3 series.
 LGPL License Terms @ref lgpl_license
 */

+/** @defgroup peripheral_apis Peripheral APIs
+ * APIs for device peripherals
+ */
+
 /** @defgroup STM32L1xx STM32L1xx
 Libraries for ST Microelectronics STM32L1xx series.

--- a/include/libopencm3/stm32/l4/doc-stm32l4.h
+++ b/include/libopencm3/stm32/l4/doc-stm32l4.h
@ -9,6 +9,10 @@ API documentation for ST Microelectronics STM32L4 Cortex M4 series.
 LGPL License Terms @ref lgpl_license
 */

+/** @defgroup peripheral_apis Peripheral APIs
+ * APIs for device peripherals
+ */
+
 /** @defgroup STM32L4xx STM32L4xx
 Libraries for ST Microelectronics STM32L4xx series.

--- a/lib/stm32/common/adc_common_v1.c
+++ b/lib/stm32/common/adc_common_v1.c
@ -1,4 +1,5 @@
-/** @addtogroup adc_file
+/** @addtogroup adc_file ADC peripheral API
+@ingroup peripheral_apis

@author @htmlonly &copy; @endhtmlonly
 2009 Edward Cheeseman <evbuilder@users.sourceforge.net>
--- a/lib/stm32/common/adc_common_v2.c
+++ b/lib/stm32/common/adc_common_v2.c
@ -1,4 +1,5 @@
-/** @addtogroup adc_file
+/** @addtogroup adc_file ADC peripheral API
+@ingroup peripheral_apis

@author @htmlonly &copy; @endhtmlonly
 2015 Karl Palsson <karlp@tweak.net.au>
--- a/lib/stm32/common/adc_common_v2_multi.c
+++ b/lib/stm32/common/adc_common_v2_multi.c
@ -1,4 +1,5 @@
-/** @addtogroup adc_file
+/** @addtogroup adc_file ADC peripheral API
+@ingroup peripheral_apis

@author @htmlonly &copy; @endhtmlonly
 2016 Karl Palsson <karlp@tweak.net.au>
--- a/lib/stm32/common/usart_common_all.c
+++ b/lib/stm32/common/usart_common_all.c
@ -1,4 +1,5 @@
-/** @addtogroup usart_file
+/** @addtogroup usart_file USART peripheral API
+@ingroup peripheral_apis

@author @htmlonly &copy; @endhtmlonly 2009 Uwe Hermann <uwe@hermann-uwe.de>

--- a/lib/stm32/common/usart_common_f124.c
+++ b/lib/stm32/common/usart_common_f124.c
@ -1,4 +1,5 @@
 /** @addtogroup usart_file
+@ingroup peripheral_apis

@author @htmlonly &copy; @endhtmlonly 2009 Uwe Hermann <uwe@hermann-uwe.de>

--- a/lib/stm32/common/usart_common_v2.c
+++ b/lib/stm32/common/usart_common_v2.c
@ -1,4 +1,5 @@
 /** @addtogroup usart_file
+@ingroup peripheral_apis

 @author @htmlonly &copy; @endhtmlonly 2016 Cem Basoglu <cem.basoglu@web.de>

--- a/lib/stm32/f0/adc.c
+++ b/lib/stm32/f0/adc.c
@ -1,8 +1,5 @@
-/** @defgroup adc_file ADC
- *
- * @ingroup STM32F0xx
- *
- * @brief <b>libopencm3 STM32F0xx Analog to Digital Converters</b>
+/** @addtogroup adc_file ADC peripheral API
+ * @ingroup peripheral_apis
 *
 * based on F3 file
 *
--- a/lib/stm32/f1/adc.c
+++ b/lib/stm32/f1/adc.c
@ -1,8 +1,5 @@
-/** @defgroup adc_file ADC
-
-@ingroup STM32F1xx
-
-@brief <b>libopencm3 STM32F1xx Analog to Digital Converters</b>
+/** @addtogroup adc_file ADC peripheral API
+@ingroup peripheral_apis

@version 1.0.0

--- a/lib/stm32/f3/adc.c
+++ b/lib/stm32/f3/adc.c
@ -1,8 +1,5 @@
-/** @defgroup adc_file ADC
- *
- * @ingroup STM32F3xx
- *
- * @brief <b>libopencm3 STM32F3xx Analog to Digital Converters</b>
+/** @addtogroup adc_file ADC peripheral API
+ * @ingroup peripheral_apis
 *
 * @author @htmlonly &copy; @endhtmlonly 2012
 * Ken Sarkies <ksarkies@internode.on.net>
--- a/lib/stm32/f4/adc.c
+++ b/lib/stm32/f4/adc.c
@ -1,8 +1,5 @@
-/** @defgroup adc_file ADC
-
-@ingroup STM32F4xx
-
-@brief <b>libopencm3 STM32F4xx Analog to Digital Converters</b>
+/** @addtogroup adc_file ADC peripheral API
+@ingroup peripheral_apis

@author @htmlonly &copy; @endhtmlonly 2012
 Ken Sarkies <ksarkies@internode.on.net>
--- a/lib/stm32/l1/adc.c
+++ b/lib/stm32/l1/adc.c
@ -1,8 +1,5 @@
-/** @defgroup adc_file ADC
-
-@ingroup STM32L1xx
-
-@brief <b>libopencm3 STM32L1xx Analog to Digital Converters</b>
+/** @addtogroup adc_file ADC peripheral API
+@ingroup peripheral_apis

@author @htmlonly &copy; @endhtmlonly 2014 Karl Palsson <karlp@tweak.net.au>

--- a/lib/stm32/l4/adc.c
+++ b/lib/stm32/l4/adc.c
@ -1,8 +1,5 @@
-/** @defgroup adc_file ADC
-
-@ingroup STM32L4xx
-
-@brief <b>libopencm3 STM32L4xx Analog to Digital Converters</b>
+/** @addtogroup adc_file ADC peripheral API
+@ingroup peripheral_apis

@author @htmlonly &copy; @endhtmlonly 2016 Karl Palsson <karlp@tweak.net.au>