MONDRIAN-1771 - method name changes and documentation based on discussio...

...ns this morning