add an explanation of assertions, small RDoc tweaks