added docstrings, fixed as per comments of Francisco