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?

[speedyleion]

@yashi what version of clang do you have on your local machine? I'm assuming that csp_rtable_set() was one example and the other functions are also failing to parse. I noticed that the code has no space between the parameter direction and the text @param[in]mask number of bits, https://github.com/libcsp/libcsp/blob/1f7701b2a53ca3766b826d61db7f45dd6416bc22/include/csp/csp_rtable.h#L37 However, based on the output in the screen shot it seems like it's putting a space in between the words.

[speedyleion]

I also just noticed the parameter in the docs is mask while the parameter in the signature is netmask

[yashi]

I tried it just now and it seems the problem is gone. I'm sorry that I can't reproduce it. Sorry for the noise.

I also just noticed the parameter in the docs is mask while the parameter in the signature is netmask

Yes that's what I thought at first but fixing it didn't change.

what version of clang do you have on your local machine?

I have many clangs installed, including 14, 15, 16, 17, 18. The default clang is 16, it this helps.

I'm assuming that csp_rtable_set() was one example and the other functions are also failing to parse.

Yes. That was I observed.