Adding comments and const

[lains]

I open this PR because I have been browsing through the code, and it often took me a while tracing the meaning of function arguments, so I wrote some comments that I thought would be interesting to share to others as doxygen comments.

Also, and more importantly, I have been adding a few const type qualifiers to input arguments passed as pointers.
There are a lot of cases where structs are passed as pointers, most often only for input (they are unmodified).
Input and output arguments passed as reference can be explained by using doxygen @param[in] and @param[out] but I think a good and visual safeguard is also to qualify them as const so that the programmer and compiler both know this argument should not be modified.
Adding const qualification is a recursive action that can lead to changing many sub-function calls, so there is quite some work to be done, probably each time starting from higher level functions, and necessarily recursively reworking the prototypes of the sub-functions they use.

[jkoan]

Doc looks good

[mvglasow]

Happy to see more Doxygen contributions. Thanks!

[pgrandin]

Nice work, thanks @lains !

[jkoan]

Öhm guys, this PR had the WIP tag set

[lains]

No worries, its was ready to merge. I just used the WIP tag because I wanted to add more of similar stuff, but I'll open new PRs for further work on this topic.

[mvglasow]

Sorry, I get trigger-happy when it comes to docs :-)

Personally, when I have docs to add, I commit them straight to trunk (after once being advised that for pure refactoring without even any code changes, there is no need to go through the whole review process).

[lains]

OK, I'll do it this way (ie: go without review for added doc only). But I think I'll still go via a PR if there are const type qualifiers added as I'm interested in getting circle CI feedback... adding const may break compilation or at least add warnings and this might be in parts of the code that are platform-specific, so I may not have seen it when compiling on my machine.