From 3580c61a256b940ab1269a11f7f1593b0596e72c Mon Sep 17 00:00:00 2001 From: Brett Profitt Date: Thu, 5 Jan 2012 12:50:37 -0800 Subject: Fixes #4243. Added docs to explain the difference between annotation_calculation and calculation. --- engine/lib/annotations.php | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/engine/lib/annotations.php b/engine/lib/annotations.php index 6e0402804..bb7d836cc 100644 --- a/engine/lib/annotations.php +++ b/engine/lib/annotations.php @@ -179,21 +179,23 @@ function update_annotation($annotation_id, $name, $value, $value_type, $owner_gu * * @param array $options Array in format: * - * annotation_names => NULL|ARR Annotation names - * - * annotation_values => NULL|ARR Annotation values - * - * annotation_ids => NULL|ARR annotation ids - * - * annotation_case_sensitive => BOOL Overall Case sensitive - * - * annotation_owner_guids => NULL|ARR guids for annotation owners - * + * annotation_names => NULL|ARR Annotation names + * annotation_values => NULL|ARR Annotation values + * annotation_ids => NULL|ARR annotation ids + * annotation_case_sensitive => BOOL Overall Case sensitive + * annotation_owner_guids => NULL|ARR guids for annotation owners * annotation_created_time_lower => INT Lower limit for created time. - * * annotation_created_time_upper => INT Upper limit for created time. + * annotation_calculation => STR Perform the MySQL function on the annotation values returned. + * Do not confuse this "annotation_calculation" option with the + * "calculation" option to elgg_get_entities_from_annotation_calculation(). + * The "annotation_calculation" option causes this function to + * return the result of performing a mathematical calculation on + * all annotations that match the query instead of ElggAnnotation + * objects. + * See the docs for elgg_get_entities_from_annotation_calculation() + * for the proper use of the "calculation" option. * - * annotation_calculation => STR Perform the MySQL function on the annotation values returned. * * @return mixed * @since 1.8.0 @@ -384,8 +386,14 @@ function elgg_list_entities_from_annotations($options = array()) { * Get entities ordered by a mathematical calculation on annotation values * * @param array $options An options array: - * 'annotation_calculation' => The calculation to use. Must be a valid MySQL function. + * 'calculation' => The calculation to use. Must be a valid MySQL function. * Defaults to sum. Result selected as 'annotation_calculation'. + * Don't confuse this "calculation" option with the + * "annotation_calculation" option to elgg_get_annotations(). + * This "calculation" option is applied to each entity's set of + * annotations and is selected as annotation_calculation for that row. + * See the docs for elgg_get_annotations() for proper use of the + * "annotation_calculation" option. * 'order_by' => The order for the sorting. Defaults to 'annotation_calculation desc'. * 'annotation_names' => The names of annotations on the entity. * 'annotation_values' => The values of annotations on the entity. -- cgit v1.2.3