doc: Update CSS for readable @retval tables

[maribu]

Contribution description

Currently now margin between the return value and its description are added in return value tables generated with the @retval command. This adds a 2em margin, which is consistent with the margin after parameter names in the parameter table.

Testing procedure

E.g. the documentation of the dht_init() function should be more readable with this.

Issues/PRs references

Noticed in #13046

[miri64]

Are you sure you mean dht_init()? It doesn't use @retval. However, dht_read() looks weird (and uses @retval). Pretty sure though, that this parsing error is not fixed with your proposal.

[miri64]

Compare

RIOT/drivers/include/dht.h

Lines 95 to 96 in 87d00ab

	* @return 0 on success
	* @return -1 on error

and

RIOT/drivers/include/dht.h

Lines 110 to 113 in 87d00ab

	* @retval `DHT_OK` Success
	* @retval `DHT_NOCSUM` Checksum error
	* @retval `DHT_TIMEOUT` Reading data timed out (check wires!)
	* @retval `DHT_NODEV` Unsupported device type specified

(my solution to "fix" this issue would be to remove the ` around the values, which (I believe) would also create references to their respective doc)

[maribu]

I meant indeed dht_init() and the missing space between e.g. "-1" and "on error".

The broken output for dht_read() (which by the way is a bug in @doxygen), is not intended to be fixed by this PR.

[miri64]

I meant indeed dht_init() and the missing space between e.g. "-1" and "on error".

Then I'm still not sure what you are trying to fix here. The doc for the dht_init() return values (as with any @return-based doc) is based on a description list <dl> of class .return not as your fix implies on a table with <td>-class .retval.

[maribu]

I see. On current version of Doxygen it generates separate table fields for key and values. Can you build the doc locally and check again?

A quick look at the HTML generated by the historic version of Doxygen seems to indicate that this would not introduce an issue there, right? But it would fix one with the current version.

[maribu]

I reported the bug of incorrectly handling markdown in @retval upstream: doxygen/doxygen#7499

[maribu]

I see. On current version of Doxygen it generates separate table fields for key and values. Can you build the doc locally and check again?

No, it is not with the version. In dht_init() the table is generated from @return commands, not by @retval commands. The space is also missing for @retval commands in the historic version (as seen in the dht_read()). The bug of incorrectly generated code highlight there is just more ugly.

[maribu]

With #13063 applied it becomes more obvious that the margin between the table columns are currently missing.

[miri64]

Ok, now I understand!

ACK, together with #13063 this results in the following—much nicer—output