Problem with forcing new line in generated documentation.

[m-kru]

Look at include/spi.h lines 149-156. They look good in header file however when it is generated to html it is all in one line, it is not clear and hard to read. doxygen supports @n special command that forces new line in generated documentation. I have added it at the beginning of each line however without any effect on generated documentation text.

[nashif]

@dbkinder can you take a look?

[m-kru]

@dbkinder Doxygen manual says:

All commands in the documentation start with a backslash (\) or an at-sign (@). If you prefer you can replace all commands starting with a backslash below by their counterparts that start with an at-sign.

I have check both options \n and @n, none of them works.

[dbkinder]

Yep... further investigation shows this is a known problem with breathe. I'm checking out the latest version (4.7.2) to see if it works and if we can switch to that.

[nashif]

i have seen some people working around this by adding <br/> in doxygen :-)

[dbkinder]

using @n or \n or <br/> all generate the same doxygen xml output that's read by sphinx/breathe, and looks like breathe doesn't honor the xml tag.

So, there is another way to fix this (as done in i2s.h) by using @param to identify the struct members being documented. For the section you've written that describes the bit field layout (with aligned columns of information) you can use 4 leading spaces to create a pre block. I'm submitting a PR to tweak spi.h with this change.

But there's another problem here: there are two include files defining the spi interface, spi.h and spi_legacy.h with structs and such with the same names, and doxygen is trying to mash them together.

[dbkinder]

P.S. You can use a blank line to force a new paragraph.

[m-kru]

Then documentation in header file will look long and weird.

[dbkinder]

@m-kru I tried to assign you as a reviewer for #1424 but you don't show up. Take a look.