Misc buffer fixes and documentation improvements from PR 1361.
Merge pull request #1947 from vohi/buffer-docs

Misc buffer fixes and documentation improvements from PR 1361.