gotcha in embed documentation and unclear error messages

The past few days I have spent chasing a bug that I would like to share with you so that others may learn from my mistakes.

My integration uses the example code as on:
http://codex.gallery2.org/Gallery2:Embedding:Integration#On-the-fly_User_Creation

However this example fails to mention that AFTER creating a user, you need to switch to the user using checkActiveUser( string $activeUserId ) otherwise newly created albums will have a 0 as the owner_id and the database will be in a unusable state.

What caused me to spend a lot of time on this issue is the slightly misleading API documentation for checkActiveUser: "No need to call directly if activeUserId is passed to init()." and activeUserId is clearly passed in init() in the on-the-fly_user_creation example.

I hope that someone can update the documentation for on-the-fly_user_creation and checkActiveUser so that others may fare better than I did.

Also the error message "item not found" that the broken databases produced was less than helpfull. Perhaps an 'item not found' should come with information on the sort of item requested (a user) and the context it is needed in (owner for an album)

best regards,

Freek