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>
Fix the omission of having bullets for the enumeration of options, as
it makes the formatting look properly vs just different lines.
Change-Id: I701f705bc03ccc2082439c3ea3c1b5053b2aac0a
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
In preparation for more strict guidelines on documentation, provide a
trouble shooting guide with the most common and obscure issues found.
The CI system will point to this guide to help committers upon doc
failures.
Change-Id: I386baea75dad0c82b58b23926e0bd32de8a0b249
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
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>
Some function *typedefs* confuse the *Sphynx* / *breathe* parser [see
the patch for full details]. Implement a workaround (defining the name
with @typedef), add workaround documentation and file a bug with the
sphinx/breathe developers.
Change-Id: I7f3dba4a53d0cc73e12f02511a5f85526f357b5f
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
Sphinx's parser gets all confused; add a workaround using @fn,
document the workaround in the contribution section; bug filed with
Sphinx for a permanent sollution.
Change-Id: I0200add092da27206b9d006bb13110c4cc37d0e4
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
Makes no sense to integrate the whole file for just a few lines, so
defaulted to remove the inclusion and just copy the lines that are
interesting.
Change-Id: I84a2218063ca7368678402b1123da34efae14f27
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
Files had been changed without the offsets being updated, so it was
generating warnings.
Change-Id: I5c7756f396cf607470da1ce6c5807e5a343491d2
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
Add missing '*/', rename <entity> to ENTITY and fix indentation so the
formatting engine recognizes the example code as C code.
Change-Id: Iff1b5c0cef5bb635ba1b39f507ff657e9ab4c338
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
