buildAmount Hook functionality changed -- difficult to use / undocumented

We recently tried to use the buildAmount hook and were faced with an input parameter ($amount) that looked significantly different from the docs in http://wiki.civicrm.org/confluence/display/CRMDOC/hook_civicrm_buildAmount.

It appears to be a price sets array with several nested items--rather than the simple array outlined in the docs. We are using the normal contribution page amounts settings (i.e. not explicitly using Price Sets).

Our preliminary pokings around to modify the array seemed to be semi-successful, but it seems like perhaps this hook has been made less dev-friendly by some other backend changes.

Wanted to raise the issue, although I'm not sure what type of issue it is. Is it a documentation issue (i.e. this is the way it is now), or is it a case of redesigning the hook somehow to be more dev-friendly.

Regardless, I assume it would break any prior uses of the hook from upgraded dbs, so it could be a significant upgrade problem for some users.