Lots of new @todos :(

14 files changed, 31 insertions, 1 deletions

diff --git a/engine/classes/ElggDiskFilestore.php b/engine/classes/ElggDiskFilestore.php
index 2d86e7c2d..7374aad35 100644
--- a/engine/classes/ElggDiskFilestore.php
+++ b/engine/classes/ElggDiskFilestore.php
@@ -60,6 +60,7 @@ class ElggDiskFilestore extends ElggFilestore {
 
 		$path = substr($fullname, 0, $ls);
 		$name = substr($fullname, $ls);
+		// @todo $name is unused, remove it or do we need to fix something?
 
 		// Try and create the directory
 		try {
diff --git a/engine/classes/ElggFile.php b/engine/classes/ElggFile.php
index 532db3617..3e9c24c17 100644
--- a/engine/classes/ElggFile.php
+++ b/engine/classes/ElggFile.php
@@ -93,6 +93,7 @@ class ElggFile extends ElggObject {
 			$container_guid = $this->container_guid;
 		}
 		$fs = $this->getFilestore();
+		// @todo add getSize() to ElggFilestore
 		return $fs->getSize($prefix, $container_guid);
 	}
 
@@ -289,6 +290,7 @@ class ElggFile extends ElggObject {
 	public function seek($position) {
 		$fs = $this->getFilestore();
 
+		// @todo add seek() to ElggFilestore
 		return $fs->seek($this->handle, $position);
 	}
 
@@ -393,6 +395,7 @@ class ElggFile extends ElggObject {
 
 			$this->filestore = new $filestore();
 			$this->filestore->setParameters($parameters);
+			// @todo explain why $parameters will always be set here (PhpStorm complains)
 		}
 
 		// this means the entity hasn't been saved so fallback to default
diff --git a/engine/classes/ElggGroup.php b/engine/classes/ElggGroup.php
index 24bdee79e..61f699f1a 100644
--- a/engine/classes/ElggGroup.php
+++ b/engine/classes/ElggGroup.php
@@ -220,6 +220,7 @@ class ElggGroup extends ElggEntity
 	 * @return array|false
 	 */
 	public function getObjects($subtype = "", $limit = 10, $offset = 0) {
+		// @todo are we deprecating this method, too?
 		return get_objects_in_group($this->getGUID(), $subtype, 0, 0, "", $limit, $offset, false);
 	}
 
@@ -233,6 +234,7 @@ class ElggGroup extends ElggEntity
 	 * @return array|false
 	 */
 	public function getFriendsObjects($subtype = "", $limit = 10, $offset = 0) {
+		// @todo are we deprecating this method, too?
 		return get_objects_in_group($this->getGUID(), $subtype, 0, 0, "", $limit, $offset, false);
 	}
 
@@ -244,6 +246,7 @@ class ElggGroup extends ElggEntity
 	 * @return array|false
 	 */
 	public function countObjects($subtype = "") {
+		// @todo are we deprecating this method, too?
 		return get_objects_in_group($this->getGUID(), $subtype, 0, 0, "", 10, 0, true);
 	}
 
diff --git a/engine/classes/ElggMenuBuilder.php b/engine/classes/ElggMenuBuilder.php
index 6da951597..0dce02be4 100644
--- a/engine/classes/ElggMenuBuilder.php
+++ b/engine/classes/ElggMenuBuilder.php
@@ -274,6 +274,8 @@ class ElggMenuBuilder {
 	 * @param ElggMenuItem $a
 	 * @param ElggMenuItem $b
 	 * @return bool
+	 *
+	 * @todo deprecate this? weight seems to be deprecated
 	 */
 	public static function compareByWeight($a, $b) {
 		$aw = $a->getWeight();
diff --git a/engine/classes/ElggPlugin.php b/engine/classes/ElggPlugin.php
index 066fd9a79..ae447bddb 100644
--- a/engine/classes/ElggPlugin.php
+++ b/engine/classes/ElggPlugin.php
@@ -597,6 +597,8 @@ class ElggPlugin extends ElggObject {
 	 * Checks if this plugin can be activated on the current
 	 * Elgg installation.
 	 *
+	 * @todo remove $site_guid param or implement it
+	 *
 	 * @param mixed $site_guid Optional site guid
 	 * @return bool
 	 */
diff --git a/engine/lib/annotations.php b/engine/lib/annotations.php
index 41a736aa1..f40a2cc6f 100644
--- a/engine/lib/annotations.php
+++ b/engine/lib/annotations.php
@@ -17,6 +17,7 @@
  */
 function row_to_elggannotation($row) {
 	if (!($row instanceof stdClass)) {
+		// @todo should throw in this case?
 		return $row;
 	}
 
diff --git a/engine/lib/calendar.php b/engine/lib/calendar.php
index 9a06c5292..e6f95934c 100644
--- a/engine/lib/calendar.php
+++ b/engine/lib/calendar.php
@@ -39,6 +39,8 @@ function get_day_end($day = null, $month = null, $year = null) {
 /**
  * Return the notable entities for a given time period.
  *
+ * @todo this function also accepts an array(type => subtypes) for 3rd arg. Should we document this?
+ *
  * @param int     $start_time     The start time as a unix timestamp.
  * @param int     $end_time       The end time as a unix timestamp.
  * @param string  $type           The type of entity (eg "user", "object" etc)
diff --git a/engine/lib/database.php b/engine/lib/database.php
index dcf50545d..2b348366d 100644
--- a/engine/lib/database.php
+++ b/engine/lib/database.php
@@ -123,6 +123,8 @@ function establish_db_link($dblinkname = "readwrite") {
 
 	// Set up cache if global not initialized and query cache not turned off
 	if ((!$DB_QUERY_CACHE) && (!$db_cache_off)) {
+		// @todo everywhere else this is assigned to array(), making it dangerous to call
+		// object methods on this. We should consider making this an plain array
 		$DB_QUERY_CACHE = new ElggStaticVariableCache('db_query_cache');
 	}
 }
diff --git a/engine/lib/entities.php b/engine/lib/entities.php
index e3535c741..25c927ac6 100644
--- a/engine/lib/entities.php
+++ b/engine/lib/entities.php
@@ -1220,6 +1220,7 @@ function elgg_get_entity_type_subtype_where_sql($table, $types, $subtypes, $pair
 			if ($subtypes) {
 				foreach ($subtypes as $subtype) {
 					// check that the subtype is valid (with ELGG_ENTITIES_NO_VALUE being a valid subtype)
+					// @todo simplify this logic
 					if (ELGG_ENTITIES_NO_VALUE === $subtype || $subtype_id = get_subtype_id($type, $subtype)) {
 						$subtype_ids[] = (ELGG_ENTITIES_NO_VALUE === $subtype) ? ELGG_ENTITIES_NO_VALUE : $subtype_id;
 					} else {
@@ -1461,6 +1462,8 @@ function elgg_list_entities(array $options = array(), $getter = 'elgg_get_entiti
  *
  * @tip Use this to generate a list of archives by month for when entities were added or updated.
  *
+ * @todo document how to pass in array for $subtype
+ *
  * @warning Months are returned in the form YYYYMM.
  *
  * @param string $type           The type of entity
diff --git a/engine/lib/input.php b/engine/lib/input.php
index bbb9ff94d..2d9bae4dd 100644
--- a/engine/lib/input.php
+++ b/engine/lib/input.php
@@ -226,6 +226,8 @@ function elgg_clear_sticky_value($form_name, $variable) {
 /**
  * Page handler for autocomplete endpoint.
  *
+ * @todo split this into functions/objects, this is way too big
+ *
  * /livesearch?q=<query>
  *
  * Other options include:
@@ -288,6 +290,7 @@ function input_livesearch_page_handler($page) {
 
 				if ($entities = get_data($query)) {
 					foreach ($entities as $entity) {
+						// @todo use elgg_get_entities (don't query in a loop!)
 						$entity = get_entity($entity->guid);
 						/* @var ElggUser $entity */
 						if (!$entity) {
@@ -338,6 +341,7 @@ function input_livesearch_page_handler($page) {
 				";
 				if ($entities = get_data($query)) {
 					foreach ($entities as $entity) {
+						// @todo use elgg_get_entities (don't query in a loop!)
 						$entity = get_entity($entity->guid);
 						/* @var ElggGroup $entity */
 						if (!$entity) {
@@ -386,6 +390,7 @@ function input_livesearch_page_handler($page) {
 
 				if ($entities = get_data($query)) {
 					foreach ($entities as $entity) {
+						// @todo use elgg_get_entities (don't query in a loop!)
 						$entity = get_entity($entity->guid);
 						/* @var ElggUser $entity */
 						if (!$entity) {
diff --git a/engine/lib/metastrings.php b/engine/lib/metastrings.php
index 7e18597a6..76c4bd8c4 100644
--- a/engine/lib/metastrings.php
+++ b/engine/lib/metastrings.php
@@ -804,6 +804,7 @@ function elgg_delete_metastring_based_object_by_id($id, $type) {
 			}
 
 			if ($metabyname_memcache) {
+				// @todo why name_id? is that even populated?
 				$metabyname_memcache->delete("{$obj->entity_guid}:{$obj->name_id}");
 			}
 		}
diff --git a/engine/lib/notification.php b/engine/lib/notification.php
index f0aff84e6..56e591192 100644
--- a/engine/lib/notification.php
+++ b/engine/lib/notification.php
@@ -174,7 +174,8 @@ function get_user_notification_settings($user_guid = 0) {
 		$user_guid = elgg_get_logged_in_user_guid();
 	}
 
-	// @todo: holy crap, really?
+	// @todo: there should be a better way now that metadata is cached. E.g. just query for MD names, then
+	// query user object directly
 	$all_metadata = elgg_get_metadata(array(
 		'guid' => $user_guid,
 		'limit' => 0
diff --git a/engine/lib/plugins.php b/engine/lib/plugins.php
index 0ea4404f3..f281b1416 100644
--- a/engine/lib/plugins.php
+++ b/engine/lib/plugins.php
@@ -91,7 +91,9 @@ function elgg_get_plugin_ids_in_dir($dir = null) {
  * @access private
  */
 function elgg_generate_plugin_entities() {
+	// @todo $site unused, can remove?
 	$site = get_config('site');
+
 	$dir = elgg_get_plugins_path();
 	$db_prefix = elgg_get_config('dbprefix');
 
diff --git a/engine/lib/system_log.php b/engine/lib/system_log.php
index 38bc4ba96..5a153afb2 100644
--- a/engine/lib/system_log.php
+++ b/engine/lib/system_log.php
@@ -10,6 +10,8 @@
 /**
  * Retrieve the system log based on a number of parameters.
  *
+ * @todo too many args, and the first arg is too confusing
+ *
  * @param int|array $by_user    The guid(s) of the user(s) who initiated the event.
  *                              Use 0 for unowned entries. Anything else falsey means anyone.
  * @param string    $event      The event you are searching on.