DOC : whole bunch of documentation clean up

what is the scope of 'this' ?