Misc buffer fixes and documentation improvements from PR 1361.

crazily long line.  In any case, the sentence doesn't belong in the @return line.  It belongs as a plain old paragraph of text between @brief and (the presently missing @param buffer line just before) @return, or as part of your @remarks.