Improve function documentation

[frans-johansson]

The docstrings in across the entire project are very basic at the moment. Let's make an effort to elaborate them with:

• Explanations for input arguments
• Explanations for the return values
• Where applicable, some additional explanations of the functionality
• Wherever np.array is used, clarify the expected shape and data contents