Re: Time to Document Callbacks

On Tue, Mar 02, 2010 at 05:08:21PM -0800, David E. Wheeler wrote:
> Howdy,
> 
> I've just committed r13835, which documents Callbacks. Yay! A few notes:

Great. Thanks!

> * 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.

Nope. No changes there.

> 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.

I was tempted to leave "The cool thing is" but opted to drop it as it
doesn't match the tone of the rest of the docs - although they are
rather dry :)

I've made assorted edits and added some extra info. A sanity check would
be most welcome.

Thanks again David!

Tim.