Documented that elgg_delete_metadata/annotations() returns null for no ops.

2 files changed, 9 insertions, 3 deletions

diff --git a/engine/lib/metadata.php b/engine/lib/metadata.php
index 34a36d86e..973d447f5 100644
--- a/engine/lib/metadata.php
+++ b/engine/lib/metadata.php
@@ -297,6 +297,8 @@ function elgg_get_metadata(array $options = array()) {
  *          This requires at least one constraint: metadata_owner_guid(s),
  *          metadata_name(s), metadata_value(s), or guid(s) must be set.
  *
+ * @warning This returns null on no ops.
+ *
  * @param array $options An options array. {@see elgg_get_metadata()}
  * @return mixed Null if the metadata name is invalid. Bool on success or fail.
  * @since 1.8.0
@@ -307,8 +309,7 @@ function elgg_delete_metadata(array $options) {
 	}
 
 	$options['metastring_type'] = 'metadata';
-	$result = elgg_batch_metastring_based_objects($options, 'elgg_batch_delete_callback');
-	return $result;
+	return elgg_batch_metastring_based_objects($options, 'elgg_batch_delete_callback');
 }
 
 /**
@@ -316,6 +317,8 @@ function elgg_delete_metadata(array $options) {
  *
  * @warning Unlike elgg_get_metadata() this will not accept an empty options array!
  *
+ * @warning This returns null on no ops.
+ *
  * @param array $options An options array. {@See elgg_get_metadata()}
  * @return mixed
  * @since 1.8.0
@@ -334,6 +337,8 @@ function elgg_disable_metadata(array $options) {
  *
  * @warning Unlike elgg_get_metadata() this will not accept an empty options array!
  *
+ * @warning This returns null on no ops.
+ *
  * @param array $options An options array. {@See elgg_get_metadata()}
  * @return mixed
  * @since 1.8.0
diff --git a/engine/lib/metastrings.php b/engine/lib/metastrings.php
index d7cc4e0bc..0c858c9d3 100644
--- a/engine/lib/metastrings.php
+++ b/engine/lib/metastrings.php
@@ -716,6 +716,8 @@ function elgg_set_metastring_based_object_enabled_by_id($id, $enabled, $type) {
  * @warning Unlike elgg_get_metastring_based_objects() this will not accept an
  * empty options array!
  *
+ * @warning This returns null on no ops.
+ *
  * @param array  $options  An options array. {@See elgg_get_metastring_based_objects()}
  * @param string $callback The callback to pass each result through
  * @return mixed
@@ -727,7 +729,6 @@ function elgg_batch_metastring_based_objects(array $options, $callback) {
 		return false;
 	}
 
-	// @todo restore once ElggBatch supports callbacks that delete rows.
 	$batch = new ElggBatch('elgg_get_metastring_based_objects', $options, $callback, 50, false);
 	$r = $batch->callbackResult;