adding more docstrings and renaming global variables to avoid local redefinition...