Re: Time to Document Callbacks

Howdy,

I've just committed r13835, which documents Callbacks. Yay! A few notes:

* Tim, you earlier said:

> I could arrange for Callbacks to only apply to methods called by the
> applicationi, and not to 'nested calls'. That's a fairly major change
> after this length of time but given the limited use Callbacks have had,
> and the lack of documentation, it's not out of the question.
> 
> The downside is that to intercept all fetched rows in a general way
> (like some kind of plugin utility module might want to do) you now have
> to add callbacks for 7 $sth fetch* methods and 6 $dbh select* methods.
> 
> Is that really preferable?

And I replied:

> Well, yes. But if there were 'fetch*' and 'select*' keys that could go to all of them at once, that would be cool, too.

I don't know if you've changed anything here. Even earlier, you wrote:

> If you're applying a callback to the "fetch" method and then your code
> calls fetchrow_hashref, for example, how do you know if the driver's
> fetchrow_hashref() method calls fetch() or fetchrow_arrayref()?
> 
> The fetch and fetchrow_arrayref method are typically aliased by the
> driver, but they're two separate methods from the DBI dispatcher's point
> of view.
> 
> Applying the same callback to both is a reasonable approach.

I'm not sure what you decided to do about this, either. But I do think that whatever side-effects of such dispatch there are should be carefully documented as well.

* I tried to include some useful examples, but one is DBD::Pg-specific and another is DBD::mysql-specific. Hope that's okay.

* I didn't mention anything about the future possibility of post-method-call callbacks or an OO interface for setting up callbacks.

I look forward to your edits and comments, and let me know if I can help with anything else for this release.

Best,

David