Add doxygen documentation to header files

[peanutfun]

Description

Doxygen is a common and very useful tool for building a documentation of C++ source code based on reading code comments in a specific format. It helps keeping the code documentation "with the code", meaning that one is less likely to update the code, but not its documentation.

GiNaCDE provides a type of "public API" by exposing certain variables and functions through its header files. Most of them are currently listed in the documentation.pdf under "Some useful commands in library". I suggest documenting at least these variables and commands with Doxygen as well.

CMake has a module which searches for Doxygen and provides useful functions for building the documentation.

Proposal

• Add doxygen docstrings to variables and commands in the GiNaCDE headers that are considered "public API", i.e. interacted with by users.
• Make CMake build the Doxygen documentation (if Doxygen is found on the host system)

Related issues

openjournals/joss-reviews#3885

[mithun218]

@peanutfun thanks for your suggestion. I am sorry to say that currently, I am entirely ignorant of Doxygen. From your explanation, it looks excellent to use Doxygen in GiNaCDE. I hope that I will be able to use Doxygen to GiNaCDE very soon.