REP-0127: minor improvements

format according to REP-0012
use ".. warning" instead of ".. todo" due to github rendering limitations
clarify wording in places