making the final corrections suggested by @mateiz and renaming a few functions to make their usage clearer