MySQL Bugs: #33655: UDF documentation is unclear on pre-5.0 and 5.0 differences

Bug #33655	UDF documentation is unclear on pre-5.0 and 5.0 differences
Submitted:	3 Jan 2008 16:06	Modified:	31 Jul 2008 17:19
Reporter:	Baron Schwartz (Basic Quality Contributor)	Email Updates:
Status:	Closed	Impact on me:	None
Category:	MySQL Server: Documentation	Severity:	S3 (Non-critical)
Version:		OS:	Any
Assigned to:	Paul DuBois	CPU Architecture:	Any
Tags:	qc

Description:
Looking at

http://dev.mysql.com/doc/refman/5.0/en/udf-aggr-calling.html
and
http://dev.mysql.com/doc/refman/5.0/en/adding-udf.html

these contradict each other a little bit on the calling sequence for aggregate functions.  The use of clear(), reset() and add() are a little unclear.  It looks like the 5 and pre-5 behavior are not explained right.  Here are the parts I see that look incorrect to me:

"xxx_add() This function is called for all rows that belong to the same group, except for the first row. You should use it to add the value in the UDF_ARGS argument to your internal summary variable. "

It looks like in pre-5, it is called for each additional row in the group, but not the first row.  In 5, it looks like it is called for the first row also.

"3. Call xxx_clear() for the first row in each new group.
4. Call xxx_add() for each new row that belongs in the same group. "

I think in 5 it should be "call xxx_clear() when a new group starts, then call xxx_add() for each row in the group."  The prototype xxx_clear() doesn't list a UDF_ARGS *args, so there would be no way for xxx_clear() to accept the first row in the group.  This would mean the first row in the group would never be passed to the UDF in 5.

How to repeat:
Doc bug

Thank you for a reasonable documentation request.

Confirmed: As of MySQL 4.1.1, you call xxx_clear() rather than xxx_reset(), and then xxx_add() is called for all rows in the group, including the first row.

Thank you for your bug report. This issue has been addressed in the documentation. The updated documentation will appear on our website shortly, and will be included in the next release of the relevant products.