simple clarification
removed/added some examples
clear docblocks