doc: fix "WARNING: Error in type declaration." in callback typedefs

Some function *typedefs* confuse the *Sphynx* / *breathe* parser [see
the patch for full details]. Implement a workaround (defining the name
with @typedef), add workaround documentation and file a bug with the
sphinx/breathe developers.

Change-Id: I7f3dba4a53d0cc73e12f02511a5f85526f357b5f
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>

doc/contribute/doxygen/typedefs.rst

@@ -23,6 +23,53 @@ No further explanation is needed regarding the type even if it is complex.
 Each complex type must be documented whereever it was defined.
 Doxygen connects the typedef and the complex type it uses automatically.
 
+Workarounds for function definitions
+************************************
+
+Some *typedefs* confuse the *Sphynx* / *breathe* parser; the construct:
+
+.. code-block:: c
+
+   /**
+    * @brief Callback API upon firing of a trigger
+    *
+    * @param "struct device *dev" Pointer to the sensor device
+    * @param "struct sensor_trigger *trigger" The trigger
+    */
+   typedef void (*sensor_trigger_handler_t)(struct device *dev,
+                                            struct sensor_trigger *trigger);
+
+might generate a warning such as::
+
+  /home/e/inaky/z/kernel-oss.git/doc/api/io_interfaces.rst:70: WARNING: Error in type declaration.
+  If typedef-like declaration:
+    Type must be either just a name or a typedef-like declaration.
+    If just a name:
+      Error in declarator or parameters and qualifiers
+      Invalid definition: Expected identifier in nested name, got keyword: int [error at 3]
+        int(* sensor_trigger_set_t) (struct device *dev, const struct sensor_trigger *trig, sensor_trigger_handler_t handler)
+        ---^
+    If typedef-like declaration:
+  ...
+
+A workaround is to force the name of the typedef with the *@typedef*
+construct:
+
+.. code-block:: c
+
+   /**
+    * @typedef sensor_trigger_handler_t
+    * @brief Callback API upon firing of a trigger
+    *
+    * @param "struct device *dev" Pointer to the sensor device
+    * @param "struct sensor_trigger *trigger" The trigger
+    */
+   typedef void (*sensor_trigger_handler_t)(struct device *dev,
+                                            struct sensor_trigger *trigger);
+
+This issue has been reported and is awaiting a final fix
+(https://github.com/michaeljones/breathe/issues/267).
+
 Type Definition Documentation Example
 *************************************
 

include/gpio.h

@@ -126,10 +126,11 @@ extern "C" {
 #define GPIO_PIN_DISABLE	(1 << 11)
 
 /**
+ * @typedef gpio_callback_t
  * @brief Define the application callback function signature.
  *
- * @param port Device struct for the GPIO device.
- * @param pin The pin that triggers the callback.
+ * @param "struct device *port" Device struct for the GPIO device.
+ * @param "uint32_t pin" The pin that triggers the callback.
  *
  * Note: This is the former callback signature used to set a unique
  *       callback (API v1.0) through gpio_set_callback(). The new
@@ -141,11 +142,13 @@ typedef void (*gpio_callback_t)(struct device *port, uint32_t pin);
 struct gpio_callback;
 
 /**
+ * @typedef gpio_callback_handler_t
  * @brief Define the application callback handler function signature
  *
- * @param port Device struct for the GPIO device.
- * @param cb Original struct gpio_callback owning this handler
- * @param pins Mask of pins that triggers the callback handler
+ * @param "struct device *port" Device struct for the GPIO device.
+ * @param "struct gpio_callback *cb" Original struct gpio_callback
+ *        owning this handler
+ * @param "uint32_t pins" Mask of pins that triggers the callback handler
  *
  * Note: cb pointer can be used to retrieve private data through
  * CONTAINER_OF() if original struct gpio_callback is stored in

include/ipm.h

@@ -38,25 +38,61 @@ extern "C" {
 #endif
 
 /**
+ * @typedef ipm_callback_t
  * @brief Callback API for incoming IPM messages
  *
  * These callbacks execute in interrupt context. Therefore, use only
  * interrupt-safe APIS. Registration of callbacks is done via
  * @a ipm_register_callback
  *
- * @param context Arbitrary context pointer provided at registration time.
- * @param id Message type identifier.
- * @param data Message data pointer. The correct amount of data to read out
+ * @param "void *context" Arbitrary context pointer provided at
+ *        registration time.
+ * @param "uint32_t id" Message type identifier.
+ * @param "volatile void *data" Message data pointer. The correct
+ *        amount of data to read out
  * must be inferred using the message id/upper level protocol.
  */
 typedef void (*ipm_callback_t)(void *context, uint32_t id, volatile void *data);
 
+/**
+ * @typedef ipm_send_t
+ * @brief Callback API to send IPM messages
+ *
+ * See @a ipm_send() for argument definitions.
+ */
 typedef int (*ipm_send_t)(struct device *ipmdev, int wait, uint32_t id,
 			  const void *data, int size);
+/**
+ * @typedef ipm_max_data_size_get_t
+ * @brief Callback API to get maximum data size
+ *
+ * See @a ipm_max_data_size_get() for argument definitions.
+ */
 typedef int (*ipm_max_data_size_get_t)(struct device *ipmdev);
+
+/**
+ * @typedef ipm_max_id_val_get_t
+ * @brief Callback API to get the ID's maximum value
+ *
+ * See @a ipm_max_id_val_get() for argument definitions.
+ */
 typedef uint32_t (*ipm_max_id_val_get_t)(struct device *ipmdev);
+
+/**
+ * @typedef ipm_register_callback_t
+ * @brief Callback API upon registration
+ *
+ * See @a ipm_register_callback() for argument definitions.
+ */
 typedef void (*ipm_register_callback_t)(struct device *port, ipm_callback_t cb,
 					void *cb_context);
+
+/**
+ * @typedef ipm_set_enabled_t
+ * @brief Callback API upon emablement of interrupts
+ *
+ * See @a ipm_set_enabled() for argument definitions.
+ */
 typedef int (*ipm_set_enabled_t)(struct device *ipmdev, int enable);
 
 struct ipm_driver_api {

include/pinmux.h

@@ -47,9 +47,29 @@ extern "C" {
 #define PINMUX_INPUT_ENABLED	(0x1)
 #define PINMUX_OUTPUT_ENABLED	(0x0)
 
+/**
+ * @typedef pmux_set
+ * @brief Callback API upon setting a PIN's function
+ * See pinmux_pin_set() for argument description
+ */
 typedef int (*pmux_set)(struct device *dev, uint32_t pin, uint32_t func);
+/**
+ * @typedef pmux_get
+ * @brief Callback API upon getting a PIN's function
+ * See pinmux_pin_get() for argument description
+ */
 typedef int (*pmux_get)(struct device *dev, uint32_t pin, uint32_t *func);
+/**
+ * @typedef pmux_pullup
+ * @brief Callback API upon setting a PIN's pullup
+ * See pinmix_pin_pullup() for argument description
+ */
 typedef int (*pmux_pullup)(struct device *dev, uint32_t pin, uint8_t func);
+/**
+ * @typedef pmux_input
+ * @brief Callback API upon setting a PIN's input function
+ * See pinmux_input() for argument description
+ */
 typedef int (*pmux_input)(struct device *dev, uint32_t pin, uint8_t func);
 
 struct pinmux_driver_api {

include/pwm.h

@@ -41,15 +41,45 @@ extern "C" {
 #include <stddef.h>
 #include <device.h>
 
+/**
+ * @typedef pwm_config_t
+ * @brief Callback API upon configuration
+ * See @a pwm_pin_configure() for argument description
+ */
 typedef int (*pwm_config_t)(struct device *dev, int access_op,
 			    uint32_t pwm, int flags);
+/**
+ * @typedef pwm_set_values_t
+ * @brief Callback API upon setting PIN values
+ * See @a pwm_pin_set_values() for argument description
+ */
 typedef int (*pwm_set_values_t)(struct device *dev, int access_op,
 				uint32_t pwm, uint32_t on, uint32_t off);
+/**
+ * @typedef pwm_set_duty_cycle_t
+ * @brief Callback API upon setting the duty cycle
+ * See @a pwm_pin_set_duty_cycle() for argument description
+ */
 typedef int (*pwm_set_duty_cycle_t)(struct device *dev, int access_op,
 				    uint32_t pwm, uint8_t duty);
+/**
+ * @typedef pwm_set_phase_t
+ * @brief Callback API upon setting the phase
+ * See @a pwm_pin_set_phase() for argument description
+ */
 typedef int (*pwm_set_phase_t)(struct device *dev, int access_op,
 				    uint32_t pwm, uint8_t phase);
+/**
+ * @typedef pwm_suspend_dev_t
+ * @brief Callback API upon suspending
+ * See @a pwm_suspend() for argument description
+ */
 typedef int (*pwm_suspend_dev_t)(struct device *dev);
+/**
+ * @typedef pwm_resume_dev_t
+ * @brief Callback API upon resuming
+ * See @a pwm_resume() for argument description
+ */
 typedef int (*pwm_resume_dev_t)(struct device *dev);
 
 /** @brief PWM driver API definition. */

include/sensor.h

@@ -198,18 +198,49 @@ enum sensor_attribute {
 	SENSOR_ATTR_CALIB_TARGET,
 };
 
+/**
+ * @typedef sensor_trigger_handler_t
+ * @brief Callback API upon firing of a trigger
+ *
+ * @param "struct device *dev" Pointer to the sensor device
+ * @param "struct sensor_trigger *trigger" The trigger
+ */
 typedef void (*sensor_trigger_handler_t)(struct device *dev,
 					 struct sensor_trigger *trigger);
 
+/**
+ * @typedef sensor_attr_set_t
+ * @brief Callback API upon setting a sensor's attributes
+ *
+ * See sensor_attr_set() for argument description
+ */
 typedef int (*sensor_attr_set_t)(struct device *dev,
 				 enum sensor_channel chan,
 				 enum sensor_attribute attr,
 				 const struct sensor_value *val);
+/**
+ * @typedef sensor_trigger_set_t
+ * @brief Callback API for setting a sensor's trigger and handler
+ *
+ * See sensor_trigger_set() for argument description
+ */
 typedef int (*sensor_trigger_set_t)(struct device *dev,
 				    const struct sensor_trigger *trig,
 				    sensor_trigger_handler_t handler);
+/**
+ * @typedef sensor_sample_fetch_t
+ * @brief Callback API for fetching data from a sensor
+ *
+ * See sensor_sample_fetch() for argument descriptor
+ */
 typedef int (*sensor_sample_fetch_t)(struct device *dev,
 				     enum sensor_channel chan);
+/**
+ * @typedef sensor_channel_get_t
+ * @brief Callback API for getting a reading from a sensor
+ *
+ * See sensor_channel_get() for argument descriptor
+ */
 typedef int (*sensor_channel_get_t)(struct device *dev,
 				    enum sensor_channel chan,
 				    struct sensor_value *val);

include/spi.h

@@ -77,12 +77,32 @@ struct spi_config {
 	uint32_t	max_sys_freq;
 };
 
+/**
+ * @typedef spi_api_configure
+ * @brief Callback API upon configuring the const controller
+ * See spi_configure() for argument description
+ */
 typedef int (*spi_api_configure)(struct device *dev,
 				 struct spi_config *config);
+/**
+ * @typedef spi_api_slave_select
+ * @brief Callback API upon selecting a slave
+ * See spi_slave_select() for argument description
+ */
 typedef int (*spi_api_slave_select)(struct device *dev, uint32_t slave);
+/**
+ * @typedef spi_api_io
+ * @brief Callback API for I/O
+ * See spi_read() and spi_write() for argument descriptions
+ */
 typedef int (*spi_api_io)(struct device *dev,
 			  const void *tx_buf, uint32_t tx_buf_len,
 			  void *rx_buf, uint32_t rx_buf_len);
+/**
+ * @typedef spi_api_control
+ * @brief Callback API upon for suspend/resume
+ * See spi_suspend() and spi_resume() for argument description
+ */
 typedef int (*spi_api_control)(struct device *dev);
 
 struct spi_driver_api {

include/uart.h

@@ -73,13 +73,19 @@ extern "C" {
 #define UART_ERROR_BREAK    (1 << 3)
 
 /**
+ * @typedef uart_irq_callback_t
  * @brief Define the application callback function signature for UART.
  *
  * @param port Device struct for the UART device.
  */
 typedef void (*uart_irq_callback_t)(struct device *port);
 
-/* For configuring IRQ on each individual UART device. Internal use only. */
+/**
+ * @typedef uart_irq_config_func_t
+ * @brief For configuring IRQ on each individual UART device.
+ *
+ * @internal
+ */
 typedef void (*uart_irq_config_func_t)(struct device *port);
 
 /** @brief UART device configuration.*/