swm050: doxygen fixups

* Include the doc-swm050.h core file that defines the base groups.
* Fix/tweak groupings to make things consistent with other targets.
* Drop redundant type information.  That's all included from the function
signatures automatically by doxygen.
* Added register descriptions from datasheet.

include/libopencm3/swm050/doc-swm050.h

@@ -0,0 +1,30 @@
+/** @mainpage libopencm3 SWM050
+
+@version 1.0.0
+
+API documentation for Synwit SWM050 series.
+
+LGPL License Terms @ref lgpl_license
+*/
+
+/** @defgroup peripheral_apis Peripheral APIs
+ * APIs for device peripherals
+ */
+
+/** @defgroup SWM050 SWM050
+Libraries for Synwit SWM050 series.
+
+@version 1.0.0
+
+LGPL License Terms @ref lgpl_license
+*/
+
+/** @defgroup SWM050_defines SWM050 Defines
+
+@brief Defined Constants and Types for the SWM050 series
+
+@version 1.0.0
+
+LGPL License Terms @ref lgpl_license
+*/
+

include/libopencm3/swm050/gpio.h

@@ -1,3 +1,11 @@
+/** @defgroup gpio_defines GPIO Defines
+ *
+ * @brief <b>Defined Constants and Types for the SWM050 General Purpose I/O</b>
+ *
+ * @ingroup SWM050_defines
+ *
+ * LGPL License Terms @ref lgpl_license
+ */
 /*
  * This file is part of the libopencm3 project.
  *
@@ -17,6 +25,8 @@
  * along with this library.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**@{*/
+
 #ifndef LIBOPENCM3_GPIO_H
 #define LIBOPENCM3_GPIO_H
 
@@ -25,7 +35,6 @@
 
 /* GPIO number definitions (for convenience) */
 /** @defgroup gpio_pin_id GPIO Pin Identifiers
-@ingroup gpio_defines
 
 @{*/
 #define GPIO0				(1 << 0)
@@ -43,28 +52,48 @@
 
 /* GPIO direction definitions */
 /** @defgroup gpio_dir GPIO Pin Direction
-@ingroup gpio_defines
 @{*/
 #define GPIO_INPUT			0x0
 #define GPIO_OUTPUT			0x1
 /**@}*/
 
+/** @defgroup gpio_registers GPIO Registers
+@{*/
+/** Data register */
 #define GPIO_DATA			MMIO32(GPIO_BASE + 0x0)
+/** Direction register */
 #define GPIO_DIR			MMIO32(GPIO_BASE + 0x4)
+/** Interrupt enable register */
+#define GPIO_INTEN			MMIO32(GPIO_BASE + 0x30)
+/** Interrupt mask register */
+#define GPIO_INTMASK			MMIO32(GPIO_BASE + 0x34)
+/** Interrupt trigger mode register */
+#define GPIO_INTLEVEL			MMIO32(GPIO_BASE + 0x38)
+/** Interrupt polarity register */
+#define GPIO_INTPOLARITY		MMIO32(GPIO_BASE + 0x3c)
+/** Interrupt status after masking */
+#define GPIO_INTSTATUS			MMIO32(GPIO_BASE + 0x40)
+/** Interrupt status before masking */
+#define GPIO_INTRAWSTATUS		MMIO32(GPIO_BASE + 0x44)
+/** Interrupt clear register */
+#define GPIO_INTEOI			MMIO32(GPIO_BASE + 0x48)
+/** External register (wat) */
 #define GPIO_EXT			MMIO32(GPIO_BASE + 0x4c)
 
-#define GPIO_INTEN			MMIO32(GPIO_BASE + 0x30)
+/**@}*/
-#define GPIO_INTMASK			MMIO32(GPIO_BASE + 0x34)
-#define GPIO_INTLEVEL			MMIO32(GPIO_BASE + 0x38)
-#define GPIO_INTPOLARITY		MMIO32(GPIO_BASE + 0x3c)
-#define GPIO_INTSTATUS			MMIO32(GPIO_BASE + 0x40)
-#define GPIO_INTRAWSTATUS		MMIO32(GPIO_BASE + 0x44)
-#define GPIO_INTEOI			MMIO32(GPIO_BASE + 0x48)
 
+/** @defgroup syscon_register SYSCON Registers
+ * @note These registers are really part of the SYSCON system control space
+ * @{*/
+/** SWD Enable register */
 #define SWD_SEL				MMIO32(SYSTEM_CON_BASE + 0x30)
+/** GPIO Alternat function selection register */
 #define GPIO_SEL			MMIO32(SYSTEM_CON_BASE + 0x80)
+/** GPIO Pull up register */
 #define GPIO_PULLUP			MMIO32(SYSTEM_CON_BASE + 0x90)
+/** GPIO Input enable register */
 #define GPIO_INEN			MMIO32(SYSTEM_CON_BASE + 0xe0)
+/*@}*/
 
 BEGIN_DECLS
 
@@ -84,3 +113,4 @@ void gpio_sel_swd(bool en);
 END_DECLS
 
 #endif
+/**@}*/

lib/swm050/gpio.c

@@ -1,3 +1,6 @@
+/** @addtogroup gpio_file GPIO peripheral API
+ * @ingroup peripheral_apis
+ */
 /*
  * This file is part of the libopencm3 project.
  *
@@ -19,13 +22,15 @@
 
 #include <libopencm3/swm050/gpio.h>
 
+/**@{*/
+
 /*---------------------------------------------------------------------------*/
 /** @brief Set a Group of Pins
 
 Set one or more pins of GPIO to 1. Please note that this chip doesn't support
 atomic pin setting.
 
-@param[in] gpios Unsigned int16. Pin identifiers @ref gpio_pin_id
+@param[in] gpios Pin identifiers @ref gpio_pin_id
 	     If multiple pins are to be changed, use bitwise OR '|' to separate
 	     them.
 */
@@ -40,7 +45,7 @@ void gpio_set(uint16_t gpios)
 Set one or more pins of GPIO to 0. Please note that this chip doesn't support
 atomic pin setting.
 
-@param[in] gpios Unsigned int16. Pin identifiers @ref gpio_pin_id
+@param[in] gpios Pin identifiers @ref gpio_pin_id
 	     If multiple pins are to be changed, use bitwise OR '|' to separate
 	     them.
 */
@@ -52,10 +57,10 @@ void gpio_clear(uint16_t gpios)
 /*---------------------------------------------------------------------------*/
 /** @brief Read a Group of Pins.
 
-@param[in] gpios Unsigned int16. Pin identifiers @ref gpio_pin_id
+@param[in] gpios Pin identifiers @ref gpio_pin_id
 	    If multiple pins are to be read, use bitwise OR '|' to separate
 	    them.
-@return Unsigned int16 value of the pin values. The bit position of the pin
+@return The pin values as a bitfield. The bit position of the pin
 	value returned corresponds to the pin number.
 */
 uint16_t gpio_get(uint16_t gpios)
@@ -68,7 +73,7 @@ uint16_t gpio_get(uint16_t gpios)
 
 Toggle one or more pins of GPIO. The non-toggled pins are not affected.
 
-@param[in] gpios Unsigned int16. Pin identifiers @ref gpio_pin_id
+@param[in] gpios Pin identifiers @ref gpio_pin_id
 	     If multiple pins are to be changed, use bitwise OR '|' to separate
 	     them.
 */
@@ -83,7 +88,7 @@ void gpio_toggle(uint16_t gpios)
 
 Set the direction of one or more pins of GPIO to input.
 
-@param[in] gpios Unsigned int16. Pin identifiers @ref gpio_pin_id
+@param[in] gpios Pin identifiers @ref gpio_pin_id
 	     If multiple pins are to be changed, use bitwise OR '|' to separate
 	     them.
 */
@@ -97,7 +102,7 @@ void gpio_input(uint16_t gpios)
 
 Set the direction of one or more pins of GPIO to output.
 
-@param[in] gpios Unsigned int16. Pin identifiers @ref gpio_pin_id
+@param[in] gpios Pin identifiers @ref gpio_pin_id
 	     If multiple pins are to be changed, use bitwise OR '|' to separate
 	     them.
 */
@@ -111,10 +116,10 @@ void gpio_output(uint16_t gpios)
 
 Select the alternative function of one or more pins of GPIO.
 
-@param[in] gpios Unsigned int16. Pin identifiers @ref gpio_pin_id
+@param[in] gpios Pin identifiers @ref gpio_pin_id
 	     If multiple pins are to be changed, use bitwise OR '|' to separate
 	     them.
-@param[in] af_en Bool. Whether alternative function is selected
+@param[in] af_en Whether alternative function is selected
 */
 void gpio_sel_af(uint16_t gpios, bool af_en)
 {
@@ -137,7 +142,7 @@ void gpio_sel_af(uint16_t gpios, bool af_en)
 
 Enable or disable the internal pull-up of one or more pins of GPIO.
 
-@param[in] gpios Unsigned int16. Pin identifiers @ref gpio_pin_id
+@param[in] gpios Pin identifiers @ref gpio_pin_id
 	     If multiple pins are to be changed, use bitwise OR '|' to separate
 	     them.
 @param[in] en Bool. Whether pull-up is enabled
@@ -155,12 +160,12 @@ void gpio_pullup(uint16_t gpios, bool en)
 /** @brief Enable the input function of a Group of Pins
 
 Enable or disable the input function of one or more pins of GPIO. Disabling
-the input function of pins can decrease the power usage of the MCU.
+the input function of pins decreases the power usage of the MCU.
 
-@param[in] gpios Unsigned int16. Pin identifiers @ref gpio_pin_id
+@param[in] gpios Pin identifiers @ref gpio_pin_id
 	     If multiple pins are to be changed, use bitwise OR '|' to separate
 	     them.
-@param[in] en Bool. Whether input function is enabled
+@param[in] en true to enable input function.
 */
 void gpio_in_en(uint16_t gpios, bool en)
 {
@@ -178,7 +183,7 @@ void gpio_in_en(uint16_t gpios, bool en)
 Enable or disable the SWD debugging port at GPIO 1/2. When SWD debugging port
 is enabled, GPIO and AF of the SWD pins will be both unavailable.
 
-@param[in] en Bool. Whether SWD is enabled
+@param[in] en true to enable SWD.
 */
 void gpio_sel_swd(bool en)
 {
@@ -188,3 +193,5 @@ void gpio_sel_swd(bool en)
 		SWD_SEL = 0;
 	}
 }
+
+/**@}*/