Doxygen: Switch to # for Macros

[hanno-becker]

As pointed out by @gilles-peskine-arm in #1309 (comment), one should consider using # in Doxygen documentation that the derived presentations include links to the cited macros.

@mkannwischer IIRC we have never run Doxygen ( / claim that it runs ), but it may still be a useful thing to do.

[gilles-peskine-arm]

This is actually probably a brain fart on my part: the documentation in headers is written in a markdown-like syntax, but it's not Doxygen syntax. I see that there's a “Doxygen lint config”, but I'm not sure what that's for.

Having typeset documentation could be useful though, whether it's with Doxygen or some other tool. (I don't have enough experience with Doxygen alternatives to give a recommendation. In my experience, Doxygen does a decent but not great job of generating HTML, but its PDF output sucks.)

[mkannwischer]

This is actually probably a brain fart on my part: the documentation in headers is written in a markdown-like syntax, but it's not Doxygen syntax. I see that there's a “Doxygen lint config”, but I'm not sure what that's for.

The goal is to have Doxygen documentation at some point, but we are not quite there.

The Doxygen lint is there to make sure Doxygen documentation builds without errors (this would e.g. catch if one forgets to document parameters of functions.)

Having typeset documentation could be useful though, whether it's with Doxygen or some other tool. (I don't have enough experience with Doxygen alternatives to give a recommendation. In my experience, Doxygen does a decent but not great job of generating HTML, but its PDF output sucks.)

It is good to know that a typeset documentation would be useful for you. So far our primary goal was to catch mistakes/inconsistencies in the docs, but maybe it is time to actually publish the HTML docs and make it pretty.

[gilles-peskine-arm]

This is actually probably a brain fart on my part: the documentation in headers is written in a markdown-like syntax, but it's not Doxygen syntax.

Ah, no, the brain fart was me today: I was looking at an old version where the comments were not in Doxygen syntax yet.

this would e.g. catch if one forgets to document parameters of functions.

You can also catch this with clang -Wdocumentation (gcc had nothing similar last time I looked). I don't know if there are things that clang -Wdocumentation catches but Doxygen doesn't.