minor clarifications and a fix in documentation
fix random float comparison error in a test