michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: fix WARNING: Invalid definition" due to unamed structs/unions

Browse source 
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>
This commit is contained in:
Inaky Perez-Gonzalez 2016-06-16 14:52:44 -07:00
commit ecc4c765cc
7 changed files with 185 additions and 30 deletions
Download patch file Download diff file Expand all files Collapse all files

15
include/toolchain.h
View file

@ -31,4 +31,19 @@
#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 */