Remove some javadoc errors; make others more pronounced ;-) (#1266)
Javadoc changes: 1) standardize opening sentences of function descriptions into the 3rd person descriptive; 2) add spurious @warn tag to throw compiler warnings indicating javadoc work TBD; 3) standardize on line-width; 4) document a few under-documented bits
Fix the bug that int overflow can bypass the range check