From 1e3c1afcacac23f4f7d34657dce6ba462b7ed97e Mon Sep 17 00:00:00 2001
From: cash <cash.costello@gmail.com>
Date: Thu, 29 Sep 2011 19:49:01 -0400
Subject: Fixes #3827 updated documentation on @return for elgg_get_entities*
 functions

---
 engine/lib/access.php           |  2 +-
 engine/lib/annotations.php      | 10 ++++------
 engine/lib/metadata.php         |  3 +--
 engine/lib/plugins.php          |  2 +-
 engine/lib/private_settings.php |  2 +-
 engine/lib/relationships.php    |  9 +++++++--
 6 files changed, 15 insertions(+), 13 deletions(-)

(limited to 'engine/lib')

diff --git a/engine/lib/access.php b/engine/lib/access.php
index 6da747463..20f57ec41 100644
--- a/engine/lib/access.php
+++ b/engine/lib/access.php
@@ -776,7 +776,7 @@ function elgg_view_access_collections($owner_guid) {
  * 	access_id => int The access ID of the entity.
  *
  * @see elgg_get_entities()
- * @return array
+ * @return mixed int if count is true, an array of entity objects, or false on failure
  * @since 1.7.0
  */
 function elgg_get_entities_from_access_id(array $options = array()) {
diff --git a/engine/lib/annotations.php b/engine/lib/annotations.php
index 80ffbe74e..9ab5a1b39 100644
--- a/engine/lib/annotations.php
+++ b/engine/lib/annotations.php
@@ -285,14 +285,12 @@ function elgg_list_annotations($options) {
  */
 
 /**
- * Returns entities based upon annotations.  Accepts the same values as
- * elgg_get_entities_from_metadata() but uses the annotations table.
+ * Returns entities based upon annotations.  Also accepts all options available
+ * to elgg_get_entities() and elgg_get_entities_from_metadata().
  *
- * NB: Entity creation time is selected as max_time. To sort based upon
+ * Entity creation time is selected as max_time. To sort based upon
  * this, pass 'order_by' => 'maxtime asc' || 'maxtime desc'
  *
- * time_created in this case will be the time the annotation was created.
- *
  * @see elgg_get_entities
  * @see elgg_get_entities_from_metadata
  *
@@ -321,7 +319,7 @@ function elgg_list_annotations($options) {
  *
  *  annotation_ids => NULL|ARR Annotation IDs
  *
- * @return array
+ * @return mixed int if count is true, an array of entity objects, or false on failure
  * @since 1.7.0
  */
 function elgg_get_entities_from_annotations(array $options = array()) {
diff --git a/engine/lib/metadata.php b/engine/lib/metadata.php
index a6b1bb43a..2becc5f3c 100644
--- a/engine/lib/metadata.php
+++ b/engine/lib/metadata.php
@@ -366,7 +366,6 @@ function elgg_enable_metadata(array $options) {
  * When in doubt, use name_value_pairs.
  *
  * @see elgg_get_entities
- * @see elgg_get_entities_from_annotations
  *
  * @param array $options Array in format:
  *
@@ -398,7 +397,7 @@ function elgg_enable_metadata(array $options) {
  *
  *  metadata_owner_guids => NULL|ARR guids for metadata owners
  *
- * @return array
+ * @return mixed int if count is true, an array of entity objects, or false on failure
  * @since 1.7.0
  */
 function elgg_get_entities_from_metadata(array $options = array()) {
diff --git a/engine/lib/plugins.php b/engine/lib/plugins.php
index fd85ed9f0..365ef6fdf 100644
--- a/engine/lib/plugins.php
+++ b/engine/lib/plugins.php
@@ -978,7 +978,7 @@ function elgg_unset_all_plugin_settings($plugin_id = null) {
  * 	plugin_user_setting_name_value_pairs_operator => NULL|STR The operator to use for combining
  *                                        (name = value) OPERATOR (name = value); default AND
  *
- * @return mixed
+ * @return mixed int if count is true, an array of entity objects, or false on failure
  */
 function elgg_get_entities_from_plugin_user_settings(array $options = array()) {
 	// if they're passing it don't bother
diff --git a/engine/lib/private_settings.php b/engine/lib/private_settings.php
index e5e7b2213..d7d819e1c 100644
--- a/engine/lib/private_settings.php
+++ b/engine/lib/private_settings.php
@@ -38,7 +38,7 @@
  *                                     their own settings.
  *
  *
- * @return array
+ * @return mixed int if count is true, an array of entity objects, or false on failure
  * @since 1.8.0
  */
 function elgg_get_entities_from_private_settings(array $options = array()) {
diff --git a/engine/lib/relationships.php b/engine/lib/relationships.php
index 9d5fd39b6..f1da65a34 100644
--- a/engine/lib/relationships.php
+++ b/engine/lib/relationships.php
@@ -235,6 +235,11 @@ function get_entity_relationships($guid, $inverse_relationship = FALSE) {
 
 /**
  * Return entities matching a given query joining against a relationship.
+ * Also accepts all options available to elgg_get_entities() and
+ * elgg_get_entities_from_metadata().
+ *
+ * @see elgg_get_entities
+ * @see elgg_get_entities_from_metadata
  *
  * @param array $options Array in format:
  *
@@ -244,7 +249,7 @@ function get_entity_relationships($guid, $inverse_relationship = FALSE) {
  *
  * 	inverse_relationship => BOOL Inverse the relationship
  *
- * @return array
+ * @return mixed int if count is true, an array of entity objects, or false on failure
  * @since 1.7.0
  */
 function elgg_get_entities_from_relationship($options) {
@@ -365,7 +370,7 @@ function elgg_list_entities_from_relationship(array $options = array()) {
  *
  * @param array $options An options array compatible with
  *                       elgg_get_entities_from_relationship()
- * @return array
+ * @return mixed int if count is true, an array of entity objects, or false on failure
  * @since 1.8.0
  */
 function elgg_get_entities_from_relationship_count(array $options = array()) {
-- 
cgit v1.2.3