Resolve phabricator feedback

Main review feedback was to apply the changes to the usage example back
into the header file.  As this was the first such change to the header,
we also resolve some low-hanging fruit in terms of bde_verify fixes, but
note that some significant issues remain, especially in documenting the
function level contracts fully.  Notably, several functions have
undocumented parameters, that I am not taking time out to understand
and document now.