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>

2 files changed, 12 insertions, 37 deletions

diff --git a/doc/contribute/doxygen/structs.rst b/doc/contribute/doxygen/structs.rst
index 4bbcfa32e..10e99d661 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 50f6a5756..821ce8ac1 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 <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
 ************************************************************