Misc buffer fixes and documentation improvements from PR 1361.

It makes no sense to claim it's a byte array if it's NULL.
Returning an invalid value would be more apt.