better document razoring code

comments in the patch