Doxygen-ify the comments on the public interface for BPI. Also, move the

two more subtle routines to the bottom and expand on their cautionary
comments a bit. No functionality or actual interface change here.

llvm-svn: 142789