aboutsummaryrefslogtreecommitdiff
path: root/engine
diff options
context:
space:
mode:
authorBrett Profitt <brett.profitt@gmail.com>2012-01-05 12:50:37 -0800
committerBrett Profitt <brett.profitt@gmail.com>2012-01-05 12:50:37 -0800
commit3580c61a256b940ab1269a11f7f1593b0596e72c (patch)
tree8641630ef15cee8837233e647590737f079a089e /engine
parent84f88c43002d3c337f3fcaf2b0f8cd4c3898081f (diff)
downloadelgg-3580c61a256b940ab1269a11f7f1593b0596e72c.tar.gz
elgg-3580c61a256b940ab1269a11f7f1593b0596e72c.tar.bz2
Fixes #4243. Added docs to explain the difference between annotation_calculation and calculation.
Diffstat (limited to 'engine')
-rw-r--r--engine/lib/annotations.php34
1 files 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.