Move detailed description higher in the page in docs

people seem to miss them as they are a bit lost between decls and defs.

close #454
add math markup to rigid body diffusion units

close #457
remove inaccurate docs

close #456
remove broken doxygen command

close #455
protect Simulator::do_optimize

close #452