Reports

Writing up what worked for me in the end, in case it helps anyone. It's probably obvious to people familiar with Doxygen, but it wasn't to me. Many thanks to @Albert for pushing me towards bits of the Doxygen documentation that I didn't know were there!

I have a file Reference.dox and the INPUT tag in my doxyfile points to it. In it I have:

/*! \page REFDOCS Reference Documents

    Comments in the code refer to the following documents:
...
*/

There are various possibilities for the "..."

1. \anchor

    \par My copy of the Coding Guidelines
    \anchor MISRA

    \par
    Hard-copy version is on Frank's desk.

This works. The Reference Documents page has the title "MISRA guidelines" and the instructions. In the documentation for the code, I get "it's coded like this to comply with rule XYZ in MISRA" and the "MISRA" is clickable. Clicking it takes me to the Reference Documents page. There, "My copy of the Coding Guidelines" is a paragraph heading in bold, and the instructions are indented below.

2. \section

    \section MISRA My copy of the Coding Guidelines

    Hard-copy version is on Frank's desk.

This works too. In the documentation for the code, I get "it's coded like this to comply with rule XYZ in My copy of the Coding Guidelines", and again that is a clickable link that gets me to the Reference Documents page. There, the heading "My copy..." is followed by the instruction text.

With a couple of documents on the page, I think this is a bit easier to read because I don't have \par all over the place.

There are probably other possibilities that I don't know about but these (probably the latter) will do for me.

Incidentally: if you get to https://www.doxygen.nl/manual/commands.html you can expand the "Special Commands" in the left sidebar to give a clickable list of the commands so you can get to them quickly. There is an alphabetical list of commands at the top of the page, but it's a long page so you don't see it, and the sidebar list is right there. BUT THE SIDEBAR LIST IS NOT ALPHABETICAL! When I was told about e.g. \cite it took me ages to find it because somehow I believed the list was alphabetical, and it was way off the bottom of the screen instead of being near the top of the list. When I found it, \anchor was right there too.

79762922