Problem
-------

building clang and CMAKE_CXX_FLAGS="-Wdocumentation" reports warnings like:

1. empty paragraph passed to '@return' command
2. '@return' command used in a comment that is attached to a function returning void
3. '@param' command used in a comment that is not attached to a function declaration
4. //<! not a Doxygen trailing comment
5. warning: HTML tag 'table' requires an end tag
6. unrecognized parameter passing direction, valid directions are '[in]', '[out]' and '[in,out]'
7. '@interface' command should not be used in a comment attached to a non-interface declaration
8. '@c' command does not have a valid word argument

Change
------

- removed empty @return and @returns from doc-comments
- removed @return on 'return-void' functions
- moved doc-comment in front of functions or typedefs
- fixed trailing comments
- wrap code in \code and \encode to avoid HTML escapes
- replaced [inout] by [in,out]
- removed '@interface' and rely on doxygen's autolink generation
- replaced @retval with @returns if the first words isn't a value

RB: 23952