update documentation
commented and asserted that some values were positive and checked that it compiles with debugging on