doc: fix WARNING: Invalid definition" due to unamed structs/unions
Fix with a workaround in unnamed unions / structs in bluetooth, i2c,
sensor and uart.
Current documentation parsers (sphinx under Doxygen) don't seem to
understand well unnamed structs / unions. They will not generate any
documentation for any documented members (see left side of
http://imgur.com/mcpBXWc).
A workaround is to make the parser think there is something like a
struct/union/enum name that is actually something with no effect to
the compiler.
Naming it with __unnamed_workaround__ ensures it is clear it is a
workaround while we wait for a final fix. It is #defined to be a NO-OP
to the compiler and rearrange the member documentation as *@param* so
we have some documentation that the non-worked around code fails to
document.
Anonymous structs/union that declare a variable are just given an
internal name.
Workarounds documented in the contribution guidelines.
Change-Id: I4d32cf444f3c5e7d2fb11581e4b41f80e93c9786
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
diff --git a/include/uart.h b/include/uart.h
index 80195c8..d5503ec 100644
--- a/include/uart.h
+++ b/include/uart.h
@@ -88,20 +88,21 @@
*/
typedef void (*uart_irq_config_func_t)(struct device *port);
-/** @brief UART device configuration.*/
+/**
+ * @brief UART device configuration.
+ *
+ * @param port Base port number
+ * @param base Memory mapped base address
+ * @param regs Register address
+ * @param sys_clk_freq System clock frequency in Hz
+ */
struct uart_device_config {
- /**
- * Base port number
- * or memory mapped base address
- * or register address
- */
- union {
+ union __unnamed_workaround__ {
uint32_t port;
uint8_t *base;
uint32_t regs;
};
-/** System clock frequency in Hz.*/
uint32_t sys_clk_freq;
#ifdef CONFIG_PCI
