revision 2 - added docstrings where appropriate