From a6aecf8ccd895c172383b0521142f1794fb002a5 Mon Sep 17 00:00:00 2001
From: Karl Palsson <karlp@tweak.net.au>
Date: Tue, 28 Jan 2020 21:50:00 +0000
Subject: [PATCH] swm050: simplify doxygen

We don't need groupings around each enum, they format nicely into a
section already.  Likewise, the doxygen _is_ documentation, so we don't
need extra versions of it in places. Also fix a few warnings generated.
---
 include/libopencm3/swm050/timer.h | 92 ++++++++++---------------------
 lib/swm050/timer.c                |  3 +-
 2 files changed, 29 insertions(+), 66 deletions(-)

diff --git a/include/libopencm3/swm050/timer.h b/include/libopencm3/swm050/timer.h
index c28ca162..8748b3a1 100644
--- a/include/libopencm3/swm050/timer.h
+++ b/include/libopencm3/swm050/timer.h
@@ -30,126 +30,75 @@
 #include <libopencm3/cm3/common.h>
 #include <libopencm3/swm050/memorymap.h>
 
-/* Timer select */
 /** @defgroup timer_select Timer Select
 @{*/
 #define TIMER_SE0	TIMER_SE0_BASE
 #define TIMER_SE1	TIMER_SE1_BASE
 /*@}*/
 
-/* Timer level definitions */
-/** @defgroup timer_level Timer Level
-@{*/
+/** Timer Level */
 enum timer_level {
 	TIMER_LEVEL_LOW,
 	TIMER_LEVEL_HIGH
 };
-/*@}*/
 
-/* Timer edge mode definitions */
-/** @defgroup timer_edge_modes Timer Edge Modes
-@{*/
+/** Timer Edge Modes */
 enum timer_edge_modes {
-	/* Trigger on rising edge */
+	/** Trigger on rising edge */
 	TIMER_EDGE_RISING,
-	/* Trigger on falling edge */
+	/** Trigger on falling edge */
 	TIMER_EDGE_FALLING
 };
-/*@}*/
 
-/* Timer operation mode definitions */
-/** @defgroup timer_operation_modes Timer Operation Modes
-@{*/
+/** Timer Operation Modes */
 enum timer_operation_modes {
 	TIMER_MODE_COUNTER,
 	TIMER_MODE_PWM,
 	TIMER_MODE_PULSE_CAPTURE,
 	TIMER_MODE_DUTY_CYCLE_CAPTURE
 };
-/*@}*/
 
-/* Timer clock source definitions */
-/** @defgroup timer_clk_src Timer Clock Source
-@{*/
+/** Timer Clock Source */
 enum timer_clk_src {
 	TIMER_CLK_INTERNAL,
 	TIMER_CLK_EXTERNAL
 };
-/*@}*/
 
-/* Timer interrupt mask definitions */
-/** @defgroup timer_int_masked Timer Interrupt Mask
-@{*/
+/** Timer Interrupt Mask */
 enum timer_int_masked {
 	TIMER_UNMASKED,
 	TIMER_MASKED
 };
-/*@}*/
 
-/* Timer loop mode definitions */
-/** @defgroup timer_loop_modes Timer Loop Modes
-@{*/
+/** Timer Loop Modes */
 enum timer_loop_modes {
 	TIMER_LOOP_MODE,
 	TIMER_SINGLE_MODE
 };
-/*@}*/
 
-/* Timer output mode definitions */
-/** @defgroup timer_output_modes Timer Output Modes
-@{*/
+/** Timer Output Modes */
 enum timer_output_modes {
 	TIMER_OUTPUT_NONE,
 	TIMER_OUTPUT_INVERT,
 	TIMER_OUTPUT_HIGH,
 	TIMER_OUTPUT_LOW
 };
-/*@}*/
 
-/* Timer PWM period definitions */
-/** @defgroup timer_pwm_period Timer PWM Periods
-@{*/
+/** Timer PWM Periods */
 enum timer_pwm_period {
 	TIMER_PERIOD_0,
 	TIMER_PERIOD_1
 };
-/*@}*/
 
-/* Timer clock divider mask */
-/** @defgroup timer_div_mask Timer Clock Divider Mask
-@{*/
+/** Timer Clock Divider Mask */
 #define TIMER_DIV_MASK			(0x3F << 16)
-/*@}*/
 
-/* Timer operation mode mask */
-/** @defgroup timer_operation_mask Timer Operation Mode Mask
-@{*/
+/** Timer Operation Mode Mask */
 #define TIMER_OPER_MODE_MASK		(0x3 << 4)
-/*@}*/
 
-/* Timer output mode mask */
-/** @defgroup timer_output_mask Timer Output Mode Mask
-@{*/
+/** Timer Output Mode Mask */
 #define TIMER_OUTP_MODE_MASK		(0x3 << 12)
-/*@}*/
 
-/* Timer subregisters */
-/** @defgroup timer_subregisters Timer Subregisters
-@{*/
-#define TIMER_CTRL_EN		1
-/** Clock source selection */
-#define TIMER_CTRL_OSCMOD	(1 << 8)
-/** Valid edge selection */
-#define TIMER_CTRL_TMOD		(1 << 16)
-/** Loop mode selection */
-#define TIMER_CTRL_LMOD		(1 << 28)
-/** Interrupt mask */
-#define TIMER_INTCTL_INTMSK	(1 << 1)
-/** Interrupt enable */
-#define TIMER_INTCTL_INTEN	1
-/*@}*/
-
-/* Timer registers */
 /** @defgroup timer_registers Timer Registers
 @{*/
 /** Timer control register */
@@ -177,6 +126,21 @@ enum timer_pwm_period {
 #define TIMER_INTFLAG(x)		MMIO32(x + 0x90)
 /*@}*/
 
+/** @defgroup timer_reg_values Timer Register Values
+@{*/
+#define TIMER_CTRL_EN		1
+/** Clock source selection */
+#define TIMER_CTRL_OSCMOD	(1 << 8)
+/** Valid edge selection */
+#define TIMER_CTRL_TMOD		(1 << 16)
+/** Loop mode selection */
+#define TIMER_CTRL_LMOD		(1 << 28)
+/** Interrupt mask */
+#define TIMER_INTCTL_INTMSK	(1 << 1)
+/** Interrupt enable */
+#define TIMER_INTCTL_INTEN	1
+/*@}*/
+
 BEGIN_DECLS
 
 void timer_counter_setup(uint32_t timer,
diff --git a/lib/swm050/timer.c b/lib/swm050/timer.c
index fe038fd4..8ae53a19 100644
--- a/lib/swm050/timer.c
+++ b/lib/swm050/timer.c
@@ -78,6 +78,7 @@ static void timer_setup_internal(uint32_t timer,
  * @param clk_src Passed to @ref timer_clock_source()
  * @param output_mode Passed to @ref timer_output_mode()
  * @param output_level Passed to @ref timer_output_level()
+ * @param target Passed to @ref timer_counter_target_value()
  */
 void timer_counter_setup(uint32_t timer,
 			 bool timer_int_en,
@@ -104,9 +105,7 @@ void timer_counter_setup(uint32_t timer,
  * @param timer Select timer @ref timer_select
  * @param timer_int_en Passed to @ref timer_int_enable()
  * @param edge_mode Passed to @ref timer_edge_mode()
- * @param loop_mode Passed to @ref timer_loop_mode()
  * @param clk_src Passed to @ref timer_clock_source()
- * @param output_mode Passed to @ref timer_output_mode()
  * @param output_level Passed to @ref timer_output_level()
  * @param period0 Passed to @ref timer_pwm_target_value()
  * @param period1 Passed to @ref timer_pwm_target_value()