fix documentation typos & style

typo corrections:
 - otherwisee --> otherwise
 - it's is --> it is
 - nuber --> number
 - will likely to use --> is likely to use
 - varaible --> variable

stylistic changes:
 - which would make --> making
escape first dash ('-') in double-dashes ('--') found in doxygen comments

This should prevent doxygen from generating bad documentation HTML pages
containing '<ndash></ndash>' where those double-dashes should be.