add code-level documentation

[argoyal]

The Python functions are without doc strings which results in less information. This needs to be improved so that inputs and outputs and the purpose of the functions are clearly defined.