Function comments
We should strive towards documenting what most of the functions does in a more detailed way. The descriptions at the top of each header file is lacking, and there should be a clear list of input parameters, output parameters and additional side-effects a function might have on the global variables of the code.