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 <inaky.perez-gonzalez@intel.com>

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
+There is no really good workaround we can use, other than live with
-parser but it is a no-op to the compiler:
+the warning and ignore it. As well, because of this, the documentation
+of the members doesn't really work yet.
 
-.. code-block:: c
+The issue reported to developers in
-
-  /**
-   * 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
 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;

doc/contribute/doxygen/troubleshooting.rst

@@ -22,6 +22,13 @@ This might be one of:
 
 - :ref:`Non-anonymous unnamed structs <unnamed_structs_var>`
 
+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
 ************************************************************

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;

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;

include/sensor.h

@@ -63,8 +63,8 @@ enum sensor_value_type {
  */
 struct sensor_value {
 	enum sensor_value_type type;
-	union __unnamed_workaround__  {
+	union  {
-		struct __unnamed_workaround__ {
+		struct {
 			int32_t val1;
 			int32_t val2;
 		};

include/toolchain.h

@@ -31,19 +31,4 @@
 #include <toolchain/other.h>
 #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 */

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;