[mlir][bufferize] Improve error message when returning allocs

The previous error message was confusing. Also improve code documentation and some minor code cleanups.

Differential Revision: https://reviews.llvm.org/D138902