Doxygen warnings about device.h macros

[nashif]

When we include tests/ in doxygen config, we start getting those warnings due to call to those macros in the code.

/home/nashif/Work/github/zephyr/include/device.h:122: warning: The following parameters of DEVICE_AND_API_INIT(dev_name, drv_name, init_fn, data, cfg_info, level, prio, api) are not documented:
  parameter 'dev_name'
  parameter 'drv_name'
  parameter 'init_fn'
  parameter 'data'
  parameter 'cfg_info'
  parameter 'level'
  parameter 'prio'
/home/nashif/Work/github/zephyr/include/device.h:145: warning: The following parameters of DEVICE_DEFINE(dev_name, drv_name, init_fn, pm_control_fn, data, cfg_info, level, prio, api) are not documented:
  parameter 'dev_name'
  parameter 'drv_name'
  parameter 'init_fn'
  parameter 'data'
  parameter 'cfg_info'
  parameter 'level'
  parameter 'prio'
  parameter 'api'
/home/nashif/Work/github/zephyr/include/device.h:122: warning: The following parameters of DEVICE_AND_API_INIT(dev_name, drv_name, init_fn, data, cfg_info, level, prio, api) are not documented:
  parameter 'dev_name'
  parameter 'drv_name'
  parameter 'init_fn'
  parameter 'data'
  parameter 'cfg_info'
  parameter 'level'
  parameter 'prio'
/home/nashif/Work/github/zephyr/include/device.h:145: warning: The following parameters of DEVICE_DEFINE(dev_name, drv_name, init_fn, pm_control_fn, data, cfg_info, level, prio, api) are not documented:
  parameter 'dev_name'
  parameter 'drv_name'
  parameter 'init_fn'
  parameter 'data'
  parameter 'cfg_info'
  parameter 'level'
  parameter 'prio'
  parameter 'api'

[nashif]

@dbkinder any idea what is going on?

[dbkinder]

@nasif That was tricky to find. What's happening is the @copydetails doxygen command isn't copying the detailed documentation of the referenced macro (notice it didn't complain about the api parameter not being documented, only the ones what were supposed to be defined by the @copydetails).

Doxygen apparenly has "issues" with function macros (those that don't end with a semicolon). Workaround is to add an entry in the PREDEFINED list in zephyr.doxyfile to remove these macros in the preprocessing step:

"DEVICE_DEFINE()=" \
"DEVICE_AND_API_INIT()=" \

And the warning goes away, and the documentation for the macros lists all the parameters as desired. I suspect some new combination of defines caused by adding the test APIs confused doxygen's handling of conditional compilation in this area.