document difference in $object from normal mode and bulk update mode

We need a note in the API.txt that reminds people that $objects are different during the addition vs. editing vs. bulk updates and that their hook_token_values should be strong enough to figure out the "right thing".

I propose something like:

When an object is created (whether it is a node or a user or a taxonomy term) the data that Pathauto hands to the token_values in the $object is in a specific format. This is the format that most people write code to handle. However, during edits and bulk updates the data may be in a totally different format. So, if you are writing a hook_token_values implementation to add special tokens, be sure to test creation, edit, and bulk update cases to make sure your code will handle it.

Thoughts?