Improve docstrings in functions

[lee-t]

Rewrite docstrings to include executable examples. This will allow for doctests in addition to improving documentation.

[lgeistlinger]

see eg the docstrings here for some good examples: https://github.com/ccb-hms/BioPlexPy

[lgeistlinger]

The documentation of each function within the codebase should contain:

• [] Title
• [] Short description
• [] Inputs (@params) (incl. data type and short description)
• [] Outputs (@returns) (incl. data type and short description)
• [] An executable example that illustrates how to use the function

[Caochris]

Thanks, I have added annotations.