rose documentation, rose macro: changes following feedback

This is a blanket pull that reflects some of the recent feedback from our users. It also tidies some documentation headers.