Bit of documentation, lots of refactoring

authors: tmeehan