Adding more comments to the new mobility code

[Miika Komu]

From Rene: can you please make sure that the update.h contains doxygen comments
along with the static functions in update.c. It would also be great to
have some more comments in update.c in the function bodies.

(Miika: I would actually prefer to move all doxygen comments to the c files
because that's what developers really read)

---

* Doxygen headers must be present for every
function and every parameter (including return) must be documente.
* Parameters
that are modified in the function must be marked in the doxygen header, too.
* Tabs and spaces are missing. Tab = 8 spaces
* The keyword const is used only 3! times. Const correctness is one of the
cornerstones for good coding. This definitely
needs to be enhanced

---

Two update.h functions are doxygened. The rest of the functions are removed
from the header because they weren't used by other files.

[René Hummen (rene-hummen)]

Someone still needs to get const-correctness into the mobility extension. Is Baris actively working on this?

[Miika Komu (miika-iki)]

I assume that he will complete the mobility code during this Fall. Can you tell how to test compile correctness (configure flags etc?)

[Miika Komu (miika-iki)]

The purpose was to add const to as many function parameters as possible.

[René Hummen (rene-hummen)]

If you add "const" to a parameter of a function that is later on modified in the function body, the compiler will through a warning (resulting in an error due to our current settings). That's about all regarding testing...

The above also depicts the sweetness of const-correctness, as the compiler will do the hard work of checking whether the content of a variable will be changed somewhere deep down in the call hierarchy. All you need to do as a programmer is to tell the compiler that you don't want the content of this variable to change.
Furthermore, const-correctness is a nice tool for documentation, as anybody else having a look at or even using your code can clearly distinguish parameters that will be changed by calling the function from parameter that will stay, well, constant.

That being said, what's the status of this bug?

[Miika Komu (miika-iki)]

No progress.