From b47b967440beb35131aefee91055b7337722d7fa Mon Sep 17 00:00:00 2001 From: Karl Palsson Date: Wed, 14 Feb 2018 23:33:26 +0000 Subject: [PATCH] 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. --- include/libopencm3/stm32/f0/doc-stm32f0.h | 4 ++++ include/libopencm3/stm32/f1/doc-stm32f1.h | 4 ++++ include/libopencm3/stm32/f2/doc-stm32f2.h | 4 ++++ include/libopencm3/stm32/f3/doc-stm32f3.h | 4 ++++ include/libopencm3/stm32/f4/doc-stm32f4.h | 4 ++++ include/libopencm3/stm32/f7/doc-stm32f7.h | 4 ++++ include/libopencm3/stm32/l0/doc-stm32l0.h | 4 ++++ include/libopencm3/stm32/l1/doc-stm32l1.h | 4 ++++ include/libopencm3/stm32/l4/doc-stm32l4.h | 4 ++++ lib/stm32/common/adc_common_v1.c | 3 ++- lib/stm32/common/adc_common_v2.c | 3 ++- lib/stm32/common/adc_common_v2_multi.c | 3 ++- lib/stm32/common/usart_common_all.c | 3 ++- lib/stm32/common/usart_common_f124.c | 1 + lib/stm32/common/usart_common_v2.c | 1 + lib/stm32/f0/adc.c | 7 ++----- lib/stm32/f1/adc.c | 7 ++----- lib/stm32/f3/adc.c | 7 ++----- lib/stm32/f4/adc.c | 7 ++----- lib/stm32/l1/adc.c | 7 ++----- lib/stm32/l4/adc.c | 7 ++----- 21 files changed, 58 insertions(+), 34 deletions(-) diff --git a/include/libopencm3/stm32/f0/doc-stm32f0.h b/include/libopencm3/stm32/f0/doc-stm32f0.h index fc26c508..9acbc159 100644 --- 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. * diff --git a/include/libopencm3/stm32/f1/doc-stm32f1.h b/include/libopencm3/stm32/f1/doc-stm32f1.h index 4e1407e2..21d1bb9c 100644 --- 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. diff --git a/include/libopencm3/stm32/f2/doc-stm32f2.h b/include/libopencm3/stm32/f2/doc-stm32f2.h index faa7f291..813ce747 100644 --- 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. diff --git a/include/libopencm3/stm32/f3/doc-stm32f3.h b/include/libopencm3/stm32/f3/doc-stm32f3.h index 5adc4edb..a562f11d 100644 --- 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. * diff --git a/include/libopencm3/stm32/f4/doc-stm32f4.h b/include/libopencm3/stm32/f4/doc-stm32f4.h index 39d70916..f0868ab8 100644 --- 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. diff --git a/include/libopencm3/stm32/f7/doc-stm32f7.h b/include/libopencm3/stm32/f7/doc-stm32f7.h index 720693f7..ba6318d3 100644 --- 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. diff --git a/include/libopencm3/stm32/l0/doc-stm32l0.h b/include/libopencm3/stm32/l0/doc-stm32l0.h index ad585d3a..2d01ca01 100644 --- 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. diff --git a/include/libopencm3/stm32/l1/doc-stm32l1.h b/include/libopencm3/stm32/l1/doc-stm32l1.h index 96bea000..7f7c0669 100644 --- 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. diff --git a/include/libopencm3/stm32/l4/doc-stm32l4.h b/include/libopencm3/stm32/l4/doc-stm32l4.h index ec4ad09e..e095ccb5 100644 --- 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. diff --git a/lib/stm32/common/adc_common_v1.c b/lib/stm32/common/adc_common_v1.c index 45d9e2b4..1974985d 100644 --- 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 © @endhtmlonly 2009 Edward Cheeseman diff --git a/lib/stm32/common/adc_common_v2.c b/lib/stm32/common/adc_common_v2.c index f8de332d..fb22d273 100644 --- 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 © @endhtmlonly 2015 Karl Palsson diff --git a/lib/stm32/common/adc_common_v2_multi.c b/lib/stm32/common/adc_common_v2_multi.c index 334af8de..d27bb32e 100644 --- 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 © @endhtmlonly 2016 Karl Palsson diff --git a/lib/stm32/common/usart_common_all.c b/lib/stm32/common/usart_common_all.c index 5c411779..4865ef1f 100644 --- 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 © @endhtmlonly 2009 Uwe Hermann diff --git a/lib/stm32/common/usart_common_f124.c b/lib/stm32/common/usart_common_f124.c index f567fcb0..653b23e2 100644 --- 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 © @endhtmlonly 2009 Uwe Hermann diff --git a/lib/stm32/common/usart_common_v2.c b/lib/stm32/common/usart_common_v2.c index 37eb5627..4bae2694 100644 --- 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 © @endhtmlonly 2016 Cem Basoglu diff --git a/lib/stm32/f0/adc.c b/lib/stm32/f0/adc.c index dead3358..2302582a 100644 --- a/lib/stm32/f0/adc.c +++ b/lib/stm32/f0/adc.c @@ -1,8 +1,5 @@ -/** @defgroup adc_file ADC - * - * @ingroup STM32F0xx - * - * @brief libopencm3 STM32F0xx Analog to Digital Converters +/** @addtogroup adc_file ADC peripheral API + * @ingroup peripheral_apis * * based on F3 file * diff --git a/lib/stm32/f1/adc.c b/lib/stm32/f1/adc.c index 7a108fc4..24e79c51 100644 --- a/lib/stm32/f1/adc.c +++ b/lib/stm32/f1/adc.c @@ -1,8 +1,5 @@ -/** @defgroup adc_file ADC - -@ingroup STM32F1xx - -@brief libopencm3 STM32F1xx Analog to Digital Converters +/** @addtogroup adc_file ADC peripheral API +@ingroup peripheral_apis @version 1.0.0 diff --git a/lib/stm32/f3/adc.c b/lib/stm32/f3/adc.c index 8d6e2e7f..9eb73dc2 100644 --- a/lib/stm32/f3/adc.c +++ b/lib/stm32/f3/adc.c @@ -1,8 +1,5 @@ -/** @defgroup adc_file ADC - * - * @ingroup STM32F3xx - * - * @brief libopencm3 STM32F3xx Analog to Digital Converters +/** @addtogroup adc_file ADC peripheral API + * @ingroup peripheral_apis * * @author @htmlonly © @endhtmlonly 2012 * Ken Sarkies diff --git a/lib/stm32/f4/adc.c b/lib/stm32/f4/adc.c index c310d301..aaa0a5c7 100644 --- a/lib/stm32/f4/adc.c +++ b/lib/stm32/f4/adc.c @@ -1,8 +1,5 @@ -/** @defgroup adc_file ADC - -@ingroup STM32F4xx - -@brief libopencm3 STM32F4xx Analog to Digital Converters +/** @addtogroup adc_file ADC peripheral API +@ingroup peripheral_apis @author @htmlonly © @endhtmlonly 2012 Ken Sarkies diff --git a/lib/stm32/l1/adc.c b/lib/stm32/l1/adc.c index b3ca8a68..1768437d 100644 --- a/lib/stm32/l1/adc.c +++ b/lib/stm32/l1/adc.c @@ -1,8 +1,5 @@ -/** @defgroup adc_file ADC - -@ingroup STM32L1xx - -@brief libopencm3 STM32L1xx Analog to Digital Converters +/** @addtogroup adc_file ADC peripheral API +@ingroup peripheral_apis @author @htmlonly © @endhtmlonly 2014 Karl Palsson diff --git a/lib/stm32/l4/adc.c b/lib/stm32/l4/adc.c index 988d79ef..e64d7ec7 100644 --- a/lib/stm32/l4/adc.c +++ b/lib/stm32/l4/adc.c @@ -1,8 +1,5 @@ -/** @defgroup adc_file ADC - -@ingroup STM32L4xx - -@brief libopencm3 STM32L4xx Analog to Digital Converters +/** @addtogroup adc_file ADC peripheral API +@ingroup peripheral_apis @author @htmlonly © @endhtmlonly 2016 Karl Palsson