Doxygen is not finding a defined group. But why?

[alexpaschoaletto]

I'm sorry if this is a newbie question; it really must be, since I apparently haven't found any similar cases on my web or documentation searches, but I'd love to find an answer anyway. So here it goes:

What's needed to make a Doxygen group "visible"?

I'm new with Doxygen and can´t make the flipping API reference show up on the docs page. On a new file created for the feature I'm developing, cbs.h, I have the following key components of the documentation:

/**
 * @file
 *
 * @brief Public Constant Bandwidth Server (CBS) APIs.
 */

...

/**
 * @defgroup cbs_apis Constant Bandwidth Server (CBS) APIs
 * @{
 */

typedef void (* cbs_callback_t)(void *arg);

/**
 * @cond INTERNAL_HIDDEN
 */

typedef struct {
    cbs_callback_t function;
    void *arg;
} cbs_job_t;

/** @endcond */

/** 
 * @brief pushes a job to a CBS queue.
 *
 * @param cbs Name of the CBS job queue.
 * @param job_function Function of the job.
 * @param cbs_period Argument to be passed to the job function.
 * @param timeout Waiting period to push the job, or one of the special values K_NO_WAIT and K_FOREVER. 
 *
 * @retval 0 Job pushed to the CBS queue.
 * @retval -ENOMSG if CBS is not defined, returned without waiting or CBS queue purged.
 * @retval -EAGAIN if waiting period timed out. 
 */
int k_cbs_push_job(cbs_t *cbs, cbs_callback_t job_function, void *job_arg, k_timeout_t timeout);

/** @} */

...

On the related .rst file of the documentation, I've included:

API Reference
**************

.. doxygengroup:: cbs_apis

However, when I try to build the documentation locally, this shows up:

 WARNING: doxygengroup: Cannot find group "cbs_apis" in doxygen xml output for project "Zephyr"

What am I missing? I tried looking for how it was done with other documents but I couldn't spot a meaninful difference. Thanks in advance.

[kartben]

Any chance you could share a link to your fork so that I can have a look?

[alexpaschoaletto]

yeah, sure, I'll just update the repo real quick. I'm not sure about your last question but if you mean the html files generated as expected, yes. This is what shows up on the API reference part:

[kartben]

I'm not sure about your last question but if you mean the html files generated as expected, yes.

i mean the HTML pages generated by Doxygen, not the Sphinx website. I.e.: http://127.0.0.1:8080/doxygen/html/

[alexpaschoaletto]

I'm not sure about your last question but if you mean the html files generated as expected, yes.

i mean the HTML pages generated by Doxygen, not the Sphinx website. I.e.: http://127.0.0.1:8080/doxygen/html/

I didn't even know this was a thing 🥲

About the repo, there you go:
https://github.com/alexpaschoaletto/zephyr/tree/cbs-as-subsystem

• docs file in doc/kernel/services/real_time_servers/cbs.rst
• cbs.h file in include/zephyr/server/cbs.h

[kartben]

https://github.com/alexpaschoaletto/zephyr/blob/cbs-as-subsystem/include/zephyr/server/cbs.h#L22C1-L23C1

This macro isn't set when you're building the documentation so the whole section is skipped.
As it's just a header, the guard probably doesn't make sense anyway. But if you really need it, you may set the macro there: https://github.com/alexpaschoaletto/zephyr/blob/cbs-as-subsystem/doc/zephyr.doxyfile.in#L2351

[kartben]

Related: https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html#rule-a-1-conditional-compilation

[alexpaschoaletto]

Oh, nice!! Huge thanks for your help, it's all showing correctly now.

Related: https://docs.zephyrproject.org/latest/contribute/coding_guidelines/index.html#rule-a-1-conditional-compilation

I'm not sure I follow this rule. Isn't the whole point of using kconfig options to conditionally exclude parts of the code that are not going to be used? Does it mean functions of a feature should be available, although empty inside, even when the feature itself is opted out?

[jukkar]

I would recommend not to add conditional Kconfig options to header file so that the any conditional compilation in the C code can use these kind of checks to compile test things:

if (IS_ENABLED(CONFIG_CBS)) {
   // do things if CBS is enabled but compile test only if CBS is disabled
}

This way you do not need to add #if defined(CONFIG_CBS) to C code (because all the needed structs etc can be found as is in the header file).