From da5446281d4e4759a4a21f481923ea11158fad3d Mon Sep 17 00:00:00 2001 From: Inaky Perez-Gonzalez Date: Thu, 30 Jun 2016 13:16:48 -0700 Subject: [PATCH] doc: revert unnamed union/struct workaround in favour of known-issues A workaround used to silence a warning in the doc generation process which involved tagging a structure with a #define can now be solved with a cleaner approach which is non-code-invasive. Backup said change and update documentation on what to do when the issue is found. Change-Id: I1ef5224cd1b2df2e57c2ace438dba90ba3fc8528 Signed-off-by: Inaky Perez-Gonzalez --- doc/contribute/doxygen/structs.rst | 42 +++------------------- doc/contribute/doxygen/troubleshooting.rst | 7 ++++ include/bluetooth/conn.h | 2 +- include/bluetooth/gatt.h | 2 +- include/sensor.h | 4 +-- include/toolchain.h | 15 -------- include/uart.h | 2 +- 7 files changed, 17 insertions(+), 57 deletions(-) diff --git a/doc/contribute/doxygen/structs.rst b/doc/contribute/doxygen/structs.rst index 4bbcfa32e08..10e99d661c2 100644 --- a/doc/contribute/doxygen/structs.rst +++ b/doc/contribute/doxygen/structs.rst @@ -60,43 +60,11 @@ This will likely generate an error such as:: sensor_value.__unnamed__ ------------^ -A workaround is to introduce something that looks like a name to the -parser but it is a no-op to the compiler: +There is no really good workaround we can use, other than live with +the warning and ignore it. As well, because of this, the documentation +of the members doesn't really work yet. -.. code-block:: c - - /** - * Workaround for documentation parser limitations - * - * Current documentation parsers (sphinx under Doxygen) don't seem to - * understand well unnamed structs / unions. 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. - * - * Current choice is to give it a 1B alignment. This basically tells - * the compiler to do what is doing now: align it wherever it thinks - * it should, as a 1B alignment "restriction" fits any other alignment - * restriction we might have. - */ - #define __unnamed_workaround__ __attribute__ ((__aligned__ (1))) - -And then use it such as: - -.. code-block:: c - - struct sensor_value { - enum sensor_value_type type; - union __unnamed_workaround__ { - struct __unnamed_workaround__ { - int32_t val1; - int32_t val2; - }; - double dval; - }; - }; - -This is currently defined in :file:`include/toolchain.h`. The issue -reported to developers in +The issue reported to developers in https://github.com/sphinx-doc/sphinx/issues/2683. When running into this issue, the member documentation has to be done @@ -113,7 +81,7 @@ with *@param* indicators, otherwise they won't be extracted: * @param sys_clk_freq System clock frequency in Hz */ struct uart_device_config { - union __unnamed_workaround__ { + union { uint32_t port; uint8_t *base; uint32_t regs; diff --git a/doc/contribute/doxygen/troubleshooting.rst b/doc/contribute/doxygen/troubleshooting.rst index 50f6a5756ad..821ce8ac184 100644 --- a/doc/contribute/doxygen/troubleshooting.rst +++ b/doc/contribute/doxygen/troubleshooting.rst @@ -22,6 +22,13 @@ This might be one of: - :ref:`Non-anonymous unnamed structs ` +We are waiting for a proper solution from the developers of +sphinx/build. In the meantime, the workaround is to document the +members with `@param` and ignore the warning adding a configuration +item to :file:`.known-issues/doc/NAME.conf`. + +Choose ``NAME`` wisely (eg: :file:`doc/bluetooth_xyz.conf`) for +something related to documentation of the bluetooth subsystem. WARNING: documented symbol `XYZ` was not declared or defined ************************************************************ diff --git a/include/bluetooth/conn.h b/include/bluetooth/conn.h index 14d2c75ef07..838aa519293 100644 --- a/include/bluetooth/conn.h +++ b/include/bluetooth/conn.h @@ -148,7 +148,7 @@ struct bt_conn_info { uint8_t role; - union __unnamed_workaround__ { + union { struct bt_conn_le_info le; struct bt_conn_br_info br; diff --git a/include/bluetooth/gatt.h b/include/bluetooth/gatt.h index f9f56f8c18f..25b39bd1f14 100644 --- a/include/bluetooth/gatt.h +++ b/include/bluetooth/gatt.h @@ -852,7 +852,7 @@ typedef uint8_t (*bt_gatt_read_func_t)(struct bt_conn *conn, uint8_t err, struct bt_gatt_read_params { bt_gatt_read_func_t func; size_t handle_count; - union __unnamed_workaround__ { + union { struct __single { uint16_t handle; uint16_t offset; diff --git a/include/sensor.h b/include/sensor.h index e394ef2c0f8..816d85b750c 100644 --- a/include/sensor.h +++ b/include/sensor.h @@ -63,8 +63,8 @@ enum sensor_value_type { */ struct sensor_value { enum sensor_value_type type; - union __unnamed_workaround__ { - struct __unnamed_workaround__ { + union { + struct { int32_t val1; int32_t val2; }; diff --git a/include/toolchain.h b/include/toolchain.h index 490aab5ea25..37bf8f491df 100644 --- a/include/toolchain.h +++ b/include/toolchain.h @@ -31,19 +31,4 @@ #include #endif -/** - * Workaround for documentation parser limitations - * - * Current documentation parsers (sphinx under Doxygen) don't seem to - * understand well unnamed structs / unions. 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. - * - * Current choice is to give it a 1B alignment. This basically tells - * the compiler to do what is doing now: align it wherever it thinks - * it should, as a 1B alignment "restriction" fits any other alignment - * restriction we might have. - */ -#define __unnamed_workaround__ __attribute__((__aligned__(1))) - #endif /* _TOOLCHAIN_H */ diff --git a/include/uart.h b/include/uart.h index 226bee9c511..360e90eea02 100644 --- a/include/uart.h +++ b/include/uart.h @@ -99,7 +99,7 @@ typedef void (*uart_irq_config_func_t)(struct device *port); * @param sys_clk_freq System clock frequency in Hz */ struct uart_device_config { - union __unnamed_workaround__ { + union { uint32_t port; uint8_t *base; uint32_t regs;