Update docs for get_entities_from_annotation_count() because it uses sum instead of count

[cash]

count_annotations() uses the slower sum rather than count. I think there is carry over into the 1.8 functions on this too. I got around a 20% speed up by switching.

[brettp]

Where are you seeing this? In 1.7 count_annotations() passes 'count' as the $sum param to get_annotations_calculate_x(), which is then used as the MySQL function.

In 1.8 count_annotations() (eventually) passes 'count' as the 'annotation_calculation' option to elgg_get_metastring_based_objects().

Sum is used for get_entities_from_annotation_count(), but this is because we want the sum of all annotations and not the count of annotations on the entity. A better name might have been egef_annotation_sum(), but since the function is deprecated by egef_annotation_calculation() it doesn't make sense to change it now.

[cash]

get_entities_from_annotation_count(): ​http://trac.elgg.org/browser/elgg/branches/1.7/engine/lib/annotations.php#L899

[brettp]

Using count() instead of sum() changes what that function does. Currently it says "return all entities ordered by the *sum of value* of all annotations named 'X' on that entity." Using count would change it to "return all entities ordered by the *number* of annotations named 'X' on that entity." I don't think we want to change this. Please reopen if needed.

[cash]

Why is it called get_entities_from_annotation_count() if it doesn't use count?

We use it for plugin downloads, correct? Why do we want to sum thousands of 1's rather than counting them?

[brettp]

I don't know why it's called that, but it's been that way since it was introduced in 1.5. Options are:

• Make the functionality match the name and possibly break sites excepting it to sum.
• Introduce in 1.7 gefa_sum() to sum and gefa_count() to count. Could possibly deprecate gefa_count() to gefa_sum() by using default args and a parent function. This would mean all sites would essentially use gefa_sum() anyway.
• Leave as is and understand it's a performance hit. It's been fixed in 1.8 anyway.

[cash]

How about: add a warning to the documentation that this function does not do what you think it does.

Then we update the plugin repository to use get_entities_from_annotations_calculate_x() directly for a big performance boost.

[brettp]

Works for me.

[brettp]

(In [svn:9129]) Fixes #3366: Added warning to get_entities_from_annotation_count() that it doesn't actually count.

[brettp]

(In [svn:9147]) Refs #3510, #3366. Added warning about count vs sum in egef_annotation_count() to trunk.