dox: a bunch of fixes for Doxygen, detected after an upgrade.

The two main problems are:
* \section commands used in class doc (supposedly they can be used only in related page documentation),
* the use of \ref to point to those sections.

Now we use markdown syntax in place of \section and we removed the use of \ref.