buttload of refactoring, and a bit of extra documentation added