Upgrade Function Bug?

[duclet]

Okay, I read the API doc about the upgrade function and it states that the function should return a message if the upgrade failed and that it shouldn't return anything or FALSE if the upgrade was successful. I did just that and it is not working. When I debug and looked at the code, it seems like what actually happening is the total opposite. If you return FALSE, then the upgrade does not take place (or at least, the database thinks it did not). If you return a message, then the the script thinks the upgrade went smoothly.

So, is this a bug (or more correctly a mis-informed documentation) on how to stop the upgrade of a module or am I missing something here?