doxygen docu and @keywords rendering

[chriesibaum]

I wanted to try your sphinx-c-autodoc to document one of my zephyr projects. The code is entirely written in c. It works quite well at least for the configuration and building. The rendered code documentation seems not to work as expected.

The source.rst looks like this

main func
=========

.. autocfunction:: main.c::main

file main.c
===========

.. autocmodule:: main.c
   :members:
   :private-members:

it is then rendered like this:

The doxygen docu and @Keywords are not really rendered properly.

versions used:

• sphinx-build: 7.2.6
• sphinx-c-autodoc: 1.3.0
• clang: 14.0.6
• ubuntu 2022.4

Do you have a clue what the issue might be? Many Thanks in advance!
Thomas

[speedyleion]

Thanks so much for taking the time to write up and provide the versions.

Looking at the docs I don't think I did a good job documenting which doxygen markups are supported. There is https://sphinx-c-autodoc.readthedocs.io/en/latest/directives.html#directive-autocfunction, but it's not clear that only the markup that clang understands in functions will be used. It's also not documented what is understood by clang.

This means the @file, @author, @version, and @copyright aren't handled. I more or less stayed away from trying to manually support any doxygen keywords, https://www.doxygen.nl/manual/commands.html.
If one wanted to handle these it may need to be done on the project side with, https://sphinx-c-autodoc.readthedocs.io/en/latest/configuration.html#c-autodoc-pre-process
I can't remember what the @file is used for in doxygen, but in sphinx the other fields are usually handled by the conf.py. Unfortunately this doesn't let one vary these entries per file or directory.

The @returns surprises me thought, that should be seen by clang, the documentation even uses the "plural" version, https://sphinx-c-autodoc.readthedocs.io/en/latest/_modules/example.c.html#c.my_func, doxygen has @return and @returns.

Are you able to share the C source code that generated the output that might help identify why the returns isn't being picked up.

[yashi]

I just noticed that I can't render niether @return or @returns on my Debian Sid machine. BUT, it works on a Ubuntu container of GitHub Actions.

The project: https://github.com/libcsp/libcsp
The latest doc: https://libcsp.github.io/libcsp/

You can see csp_rtable_set() is rendered perfectly. But on my local machine, it's rendered like this:

https://github.com/libcsp/libcsp/actions/runs/9405110214 is the last doc build on GitHub Actions.

Things I've tried (and failed):

• Update Sphinx to v7.3.7
• Downgrade sphinx_c_autodoc to v1.2.1
• Switched from @return to @returns

Does anybody have any idea?