Moved some documentation inside corresponding methods where it can be found by edoc, and tidied up the code a bit
Moved 'DEPRECATED' method to bottom of module - it's three years old and probably not needed any more
Major refactoring of compara components to move big chunks of data-munging into Object