Change to Javadoc code commenting

[Gregg Young]

If enough contributors request it, I could be convinced to switch to javadoc style comments so that the code could be processed by doxygen. Javadoc comments are a bit bulkier than my personal style, but sometimes it's useful to have text descriptions of the parameter and return values. My preference is to name variables so that it's obvious how they are intended to be used. For example, I much prefer variable names like ok and fail to the generic ret that one often sees.