PHPDoc update in db/cookies, db/events, db/post-update and db/recalc

qa-include/app/post-update.php

@@ -326,7 +326,7 @@ function qa_question_set_hidden($oldquestion, $hidden, $userid, $handle, $cookie
  * @param string $cookieid
  * @param array $answers
  * @param array $commentsfollows
- * @param int $closepost
+ * @param array|null $closepost
  */
 function qa_question_set_status($oldquestion, $status, $userid, $handle, $cookieid, $answers, $commentsfollows, $closepost = null)
 {

qa-include/db/cookies.php

@@ -27,8 +27,8 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Create a new random cookie for $ipaddress and insert into database, returning it
- * @param $ipaddress
- * @return null|string
+ * @param string $ipaddress
+ * @return string|null
  */
 function qa_db_cookie_create($ipaddress)
 {
@@ -53,8 +53,8 @@ function qa_db_cookie_create($ipaddress)
 
 /**
  * Note in database that a write operation has been done by user identified by $cookieid and from $ipaddress
- * @param $cookieid
- * @param $ipaddress
+ * @param string $cookieid
+ * @param string $ipaddress
  */
 function qa_db_cookie_written($cookieid, $ipaddress)
 {
@@ -67,7 +67,7 @@ function qa_db_cookie_written($cookieid, $ipaddress)
 
 /**
  * Return whether $cookieid exists in database
- * @param $cookieid
+ * @param string $cookieid
  * @return bool
  */
 function qa_db_cookie_exists($cookieid)

qa-include/db/events.php

@@ -31,13 +31,13 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
  * event time or leave as null to use now. This will add the event both to the entity's shared stream, and the
  * individual user streams for any users following the entity not via its shared stream (See long comment in
  * /qa-include/db/favorites.php). Also handles truncation.
- * @param $entitytype
- * @param $entityid
- * @param $questionid
- * @param $lastpostid
- * @param $updatetype
- * @param $lastuserid
- * @param $timestamp
+ * @param string $entitytype
+ * @param int $entityid
+ * @param int $questionid
+ * @param int $lastpostid
+ * @param string $updatetype
+ * @param mixed $lastuserid
+ * @param int|null $timestamp
  */
 function qa_db_event_create_for_entity($entitytype, $entityid, $questionid, $lastpostid, $updatetype, $lastuserid, $timestamp = null)
 {
@@ -116,12 +116,12 @@ function qa_db_event_create_for_entity($entitytype, $entityid, $questionid, $las
  * notification which is relevant for them, e.g. if someone answers their question). The event of type $updatetype
  * relates to $lastpostid whose antecedent question is $questionid, and was caused by $lastuserid. Pass a unix
  * $timestamp for the event time or leave as null to use now. Also handles truncation of event streams.
- * @param $userid
- * @param $questionid
- * @param $lastpostid
- * @param $updatetype
- * @param $lastuserid
- * @param $timestamp
+ * @param mixed $userid
+ * @param int $questionid
+ * @param int $lastpostid
+ * @param string $updatetype
+ * @param mixed $lastuserid
+ * @param int|null $timestamp
  */
 function qa_db_event_create_not_entity($userid, $questionid, $lastpostid, $updatetype, $lastuserid, $timestamp = null)
 {
@@ -142,8 +142,8 @@ function qa_db_event_create_not_entity($userid, $questionid, $lastpostid, $updat
 /**
  * Trim the number of events in the event stream for $userid. If an event was just added for a particular question,
  * pass the question's id in $questionid (to help focus the truncation).
- * @param $userid
- * @param $questionid
+ * @param mixed $userid
+ * @param int|null $questionid
  */
 function qa_db_user_events_truncate($userid, $questionid = null)
 {

qa-include/db/post-update.php

@@ -30,10 +30,10 @@ require_once QA_INCLUDE_DIR . 'app/updates.php';
 
 /**
  * Update the selected answer in the database for $questionid to $selchildid, and optionally record that $lastuserid did it from $lastip
- * @param $questionid
- * @param $selchildid
- * @param $lastuserid
- * @param $lastip
+ * @param int $questionid
+ * @param int|null $selchildid
+ * @param mixed|null $lastuserid
+ * @param string|null $lastip
  */
 function qa_db_post_set_selchildid($questionid, $selchildid, $lastuserid = null, $lastip = null)
 {
@@ -61,10 +61,10 @@ function qa_db_post_set_selchildid($questionid, $selchildid, $lastuserid = null,
 /**
  * Set $questionid to be closed by post $closedbyid (null if not closed) in the database, and optionally record that
  * $lastuserid did it from $lastip
- * @param $questionid
- * @param $closedbyid
- * @param $lastuserid
- * @param $lastip
+ * @param int $questionid
+ * @param int $closedbyid
+ * @param mixed|null $lastuserid
+ * @param string|null $lastip
  */
 function qa_db_post_set_closed($questionid, $closedbyid, $lastuserid = null, $lastip = null)
 {
@@ -84,10 +84,10 @@ function qa_db_post_set_closed($questionid, $closedbyid, $lastuserid = null, $la
 
 /**
  * Set the type in the database of $postid to $type, and optionally record that $lastuserid did it from $lastip
- * @param $postid
- * @param $type
- * @param $lastuserid
- * @param $lastip
+ * @param int $postid
+ * @param string $type
+ * @param mixed|null $lastuserid
+ * @param string|null $lastip
  * @param string $updatetype
  */
 function qa_db_post_set_type($postid, $type, $lastuserid = null, $lastip = null, $updatetype = QA_UPDATE_TYPE)
@@ -109,10 +109,10 @@ function qa_db_post_set_type($postid, $type, $lastuserid = null, $lastip = null,
 /**
  * Set the parent in the database of $postid to $parentid, and optionally record that $lastuserid did it from $lastip
  * (if at least one is specified)
- * @param $postid
- * @param $parentid
- * @param $lastuserid
- * @param $lastip
+ * @param int $postid
+ * @param int $parentid
+ * @param mixed|null $lastuserid
+ * @param string|null $lastip
  */
 function qa_db_post_set_parent($postid, $parentid, $lastuserid = null, $lastip = null)
 {
@@ -134,16 +134,16 @@ function qa_db_post_set_parent($postid, $parentid, $lastuserid = null, $lastip =
  * Set the text fields in the database of $postid to $title, $content, $tagstring, $notify and $name, and record that
  * $lastuserid did it from $lastip (if at least one is specified) with $updatetype. For backwards compatibility if $name
  * is null then the name will not be changed.
- * @param $postid
- * @param $title
- * @param $content
- * @param $format
- * @param $tagstring
- * @param $notify
- * @param $lastuserid
- * @param $lastip
+ * @param int $postid
+ * @param string $title
+ * @param string $content
+ * @param string $format
+ * @param string $tagstring
+ * @param bool $notify
+ * @param mixed|null $lastuserid
+ * @param string|null $lastip
  * @param string $updatetype
- * @param $name
+ * @param string|null $name
  */
 function qa_db_post_set_content($postid, $title, $content, $format, $tagstring, $notify, $lastuserid = null, $lastip = null, $updatetype = QA_UPDATE_CONTENT, $name = null)
 {
@@ -164,8 +164,8 @@ function qa_db_post_set_content($postid, $title, $content, $format, $tagstring,
 
 /**
  * Set the author in the database of $postid to $userid, and set the lastuserid to $userid as well if appropriate
- * @param $postid
- * @param $userid
+ * @param int $postid
+ * @param mixed $userid
  */
 function qa_db_post_set_userid($postid, $userid)
 {
@@ -179,10 +179,10 @@ function qa_db_post_set_userid($postid, $userid)
 /**
  * Set the (exact) category in the database of $postid to $categoryid, and optionally record that $lastuserid did it from
  * $lastip (if at least one is specified)
- * @param $postid
- * @param $categoryid
- * @param $lastuserid
- * @param $lastip
+ * @param int $postid
+ * @param int $categoryid
+ * @param mixed|null $lastuserid
+ * @param string|null $lastip
  */
 function qa_db_post_set_category($postid, $categoryid, $lastuserid = null, $lastip = null)
 {
@@ -202,12 +202,12 @@ function qa_db_post_set_category($postid, $categoryid, $lastuserid = null, $last
 
 /**
  * Set the category path in the database of each of $postids to $path retrieved via qa_db_post_get_category_path()
- * @param $postids
- * @param $path
+ * @param array $postids
+ * @param array $path
  */
 function qa_db_posts_set_category_path($postids, $path)
 {
-	if (count($postids)) {
+	if (!empty($postids)) {
 		// requires QA_CATEGORY_DEPTH=4
 		qa_db_query_sub(
 			'UPDATE ^posts SET categoryid=#, catidpath1=#, catidpath2=#, catidpath3=# WHERE postid IN (#)',
@@ -219,8 +219,8 @@ function qa_db_posts_set_category_path($postids, $path)
 
 /**
  * Set the created date of $postid to $created, which is a unix timestamp. If created is null, set to now.
- * @param $postid
- * @param $created
+ * @param int $postid
+ * @param int|null $created
  */
 function qa_db_post_set_created($postid, $created)
 {
@@ -240,8 +240,8 @@ function qa_db_post_set_created($postid, $created)
 
 /**
  * Set the last updated date of $postid to $updated, which is a unix timestamp. If updated is null, set to now.
- * @param $postid
- * @param $updated
+ * @param int $postid
+ * @param int|null $updated
  */
 function qa_db_post_set_updated($postid, $updated)
 {
@@ -261,7 +261,7 @@ function qa_db_post_set_updated($postid, $updated)
 
 /**
  * Deletes post $postid from the database (will also delete any votes on the post due to foreign key cascading)
- * @param $postid
+ * @param int $postid
  */
 function qa_db_post_delete($postid)
 {
@@ -274,7 +274,7 @@ function qa_db_post_delete($postid)
 
 /**
  * Return an array of wordids that were indexed in the database for the title of $postid
- * @param $postid
+ * @param int $postid
  * @return array
  */
 function qa_db_titlewords_get_post_wordids($postid)
@@ -288,7 +288,7 @@ function qa_db_titlewords_get_post_wordids($postid)
 
 /**
  * Remove all entries in the database index of title words for $postid
- * @param $postid
+ * @param int $postid
  */
 function qa_db_titlewords_delete_post($postid)
 {
@@ -301,7 +301,7 @@ function qa_db_titlewords_delete_post($postid)
 
 /**
  * Return an array of wordids that were indexed in the database for the content of $postid
- * @param $postid
+ * @param int $postid
  * @return array
  */
 function qa_db_contentwords_get_post_wordids($postid)
@@ -315,7 +315,7 @@ function qa_db_contentwords_get_post_wordids($postid)
 
 /**
  * Remove all entries in the database index of content words for $postid
- * @param $postid
+ * @param int $postid
  */
 function qa_db_contentwords_delete_post($postid)
 {
@@ -328,7 +328,7 @@ function qa_db_contentwords_delete_post($postid)
 
 /**
  * Return an array of wordids that were indexed in the database for the individual words in tags of $postid
- * @param $postid
+ * @param int $postid
  * @return array
  */
 function qa_db_tagwords_get_post_wordids($postid)
@@ -342,7 +342,7 @@ function qa_db_tagwords_get_post_wordids($postid)
 
 /**
  * Remove all entries in the database index of individual words in tags of $postid
- * @param $postid
+ * @param int $postid
  */
 function qa_db_tagwords_delete_post($postid)
 {
@@ -355,7 +355,7 @@ function qa_db_tagwords_delete_post($postid)
 
 /**
  * Return an array of wordids that were indexed in the database for the whole tags of $postid
- * @param $postid
+ * @param int $postid
  * @return array
  */
 function qa_db_posttags_get_post_wordids($postid)
@@ -369,7 +369,7 @@ function qa_db_posttags_get_post_wordids($postid)
 
 /**
  * Remove all entries in the database index of whole tags for $postid
- * @param $postid
+ * @param int $postid
  */
 function qa_db_posttags_delete_post($postid)
 {
@@ -382,12 +382,12 @@ function qa_db_posttags_delete_post($postid)
 
 /**
  * Return the array $postids containing only those elements which are the postid of a question in the database
- * @param $postids
+ * @param array $postids
  * @return array
  */
 function qa_db_posts_filter_q_postids($postids)
 {
-	if (count($postids)) {
+	if (!empty($postids)) {
 		return qa_db_read_all_values(qa_db_query_sub(
 			"SELECT postid FROM ^posts WHERE type='Q' AND postid IN (#)",
 			$postids
@@ -400,12 +400,12 @@ function qa_db_posts_filter_q_postids($postids)
 
 /**
  * Return an array of all the userids of authors of posts in the array $postids
- * @param $postids
+ * @param array $postids
  * @return array
  */
 function qa_db_posts_get_userids($postids)
 {
-	if (count($postids)) {
+	if (!empty($postids)) {
 		return qa_db_read_all_values(qa_db_query_sub(
 			"SELECT DISTINCT userid FROM ^posts WHERE postid IN (#) AND userid IS NOT NULL",
 			$postids

qa-include/db/recalc.php

@@ -31,6 +31,7 @@ require_once QA_INCLUDE_DIR . 'db/post-create.php';
 
 /**
  * Return the number of custom pages currently in the database
+ * @return string
  */
 function qa_db_count_pages()
 {
@@ -42,8 +43,8 @@ function qa_db_count_pages()
 
 /**
  * Return the information to reindex up to $count pages starting from $startpageid in the database
- * @param $startpageid
- * @param $count
+ * @param int $startpageid
+ * @param int $count
  * @return array
  */
 function qa_db_pages_get_for_reindexing($startpageid, $count)
@@ -59,8 +60,8 @@ function qa_db_pages_get_for_reindexing($startpageid, $count)
 
 /**
  * Return the information required to reindex up to $count posts starting from $startpostid in the database
- * @param $startpostid
- * @param $count
+ * @param int $startpostid
+ * @param int $count
  * @return array
  */
 function qa_db_posts_get_for_reindexing($startpostid, $count)
@@ -74,8 +75,8 @@ function qa_db_posts_get_for_reindexing($startpostid, $count)
 
 /**
  * Prepare posts $firstpostid to $lastpostid for reindexing in the database by removing their prior index entries
- * @param $firstpostid
- * @param $lastpostid
+ * @param int $firstpostid
+ * @param int $lastpostid
  */
 function qa_db_prepare_for_reindexing($firstpostid, $lastpostid)
 {
@@ -103,7 +104,7 @@ function qa_db_prepare_for_reindexing($firstpostid, $lastpostid)
 
 /**
  * Remove any rows in the database word indexes with postid from $firstpostid upwards
- * @param $firstpostid
+ * @param int $firstpostid
  */
 function qa_db_truncate_indexes($firstpostid)
 {
@@ -131,6 +132,7 @@ function qa_db_truncate_indexes($firstpostid)
 
 /**
  * Return the number of words currently referenced in the database
+ * @return string
  */
 function qa_db_count_words()
 {
@@ -142,8 +144,8 @@ function qa_db_count_words()
 
 /**
  * Return the ids of up to $count words in the database starting from $startwordid
- * @param $startwordid
- * @param $count
+ * @param int $startwordid
+ * @param int $count
  * @return array
  */
 function qa_db_words_prepare_for_recounting($startwordid, $count)
@@ -157,8 +159,8 @@ function qa_db_words_prepare_for_recounting($startwordid, $count)
 
 /**
  * Recalculate the cached counts for words $firstwordid to $lastwordid in the database
- * @param $firstwordid
- * @param $lastwordid
+ * @param int $firstwordid
+ * @param int $lastwordid
  */
 function qa_db_words_recount($firstwordid, $lastwordid)
 {
@@ -193,8 +195,8 @@ function qa_db_words_recount($firstwordid, $lastwordid)
 
 /**
  * Return the ids of up to $count posts in the database starting from $startpostid
- * @param $startpostid
- * @param $count
+ * @param int $startpostid
+ * @param int $count
  * @return array
  */
 function qa_db_posts_get_for_recounting($startpostid, $count)
@@ -208,8 +210,8 @@ function qa_db_posts_get_for_recounting($startpostid, $count)
 
 /**
  * Recalculate the cached vote counts for posts $firstpostid to $lastpostid in the database
- * @param $firstpostid
- * @param $lastpostid
+ * @param int $firstpostid
+ * @param int $lastpostid
  */
 function qa_db_posts_votes_recount($firstpostid, $lastpostid)
 {
@@ -223,9 +225,10 @@ function qa_db_posts_votes_recount($firstpostid, $lastpostid)
 
 
 /**
- * Recalculate the cached answer counts for posts $firstpostid to $lastpostid in the database, along with the highest netvotes of any of their answers
- * @param $firstpostid
- * @param $lastpostid
+ * Recalculate the cached answer counts for posts $firstpostid to $lastpostid in the database, along with the highest
+ * netvotes of any of their answers
+ * @param int $firstpostid
+ * @param int $lastpostid
  */
 function qa_db_posts_answers_recount($firstpostid, $lastpostid)
 {
@@ -243,10 +246,10 @@ function qa_db_posts_answers_recount($firstpostid, $lastpostid)
 // For recalculating user points...
 
 /**
- * Return the ids of up to $count users in the database starting from $startuserid
+ * Return the ids of up to $count users in the database starting from $startuserid.
  * If using single sign-on integration, base this on user activity rather than the users table which we don't have
- * @param $startuserid
- * @param $count
+ * @param int $startuserid
+ * @param int $count
  * @return array
  */
 function qa_db_users_get_for_recalc_points($startuserid, $count)
@@ -267,8 +270,8 @@ function qa_db_users_get_for_recalc_points($startuserid, $count)
 
 /**
  * Recalculate all userpoints columns for users $firstuserid to $lastuserid in the database
- * @param $firstuserid
- * @param $lastuserid
+ * @param mixed $firstuserid
+ * @param mixed $lastuserid
  */
 function qa_db_users_recalc_points($firstuserid, $lastuserid)
 {
@@ -324,7 +327,7 @@ function qa_db_users_recalc_points($firstuserid, $lastuserid)
 
 /**
  * Remove any rows in the userpoints table where userid is greater than $lastuserid
- * @param $lastuserid
+ * @param mixed $lastuserid
  */
 function qa_db_truncate_userpoints($lastuserid)
 {
@@ -339,8 +342,8 @@ function qa_db_truncate_userpoints($lastuserid)
 
 /**
  * Return the ids of up to $count questions in the database starting from $startpostid
- * @param $startpostid
- * @param $count
+ * @param int $startpostid
+ * @param int $count
  * @return array
  */
 function qa_db_qs_get_for_event_refilling($startpostid, $count)
@@ -356,8 +359,8 @@ function qa_db_qs_get_for_event_refilling($startpostid, $count)
 
 /**
  * Return the ids of up to $count posts (including queued/hidden) in the database starting from $startpostid
- * @param $startpostid
- * @param $count
+ * @param int $startpostid
+ * @param int $count
  * @return array
  */
 function qa_db_posts_get_for_recategorizing($startpostid, $count)
@@ -372,8 +375,8 @@ function qa_db_posts_get_for_recategorizing($startpostid, $count)
 /**
  * Recalculate the (exact) categoryid for the posts (including queued/hidden) between $firstpostid and $lastpostid
  * in the database, where the category of comments and answers is set by the category of the antecedent question
- * @param $firstpostid
- * @param $lastpostid
+ * @param int $firstpostid
+ * @param int $lastpostid
  */
 function qa_db_posts_recalc_categoryid($firstpostid, $lastpostid)
 {
@@ -386,8 +389,8 @@ function qa_db_posts_recalc_categoryid($firstpostid, $lastpostid)
 
 /**
  * Return the ids of up to $count categories in the database starting from $startcategoryid
- * @param $startcategoryid
- * @param $count
+ * @param int $startcategoryid
+ * @param int $count
  * @return array
  */
 function qa_db_categories_get_for_recalcs($startcategoryid, $count)
@@ -403,9 +406,9 @@ function qa_db_categories_get_for_recalcs($startcategoryid, $count)
 
 /**
  * Return the ids of up to $limit posts of $type that can be deleted from the database (i.e. have no dependents)
- * @param $type
+ * @param string $type
  * @param int $startpostid
- * @param $limit
+ * @param int|null $limit
  * @return array
  */
 function qa_db_posts_get_for_deleting($type, $startpostid = 0, $limit = null)
@@ -423,6 +426,7 @@ function qa_db_posts_get_for_deleting($type, $startpostid = 0, $limit = null)
 
 /**
  * Return the number of blobs whose content is stored in the database, rather than on disk
+ * @return string
  */
 function qa_db_count_blobs_in_db()
 {
@@ -432,7 +436,7 @@ function qa_db_count_blobs_in_db()
 
 /**
  * Return the id, content and format of the first blob whose content is stored in the database starting from $startblobid
- * @param $startblobid
+ * @param int $startblobid
  * @return array|null
  */
 function qa_db_get_next_blob_in_db($startblobid)
@@ -446,6 +450,7 @@ function qa_db_get_next_blob_in_db($startblobid)
 
 /**
  * Return the number of blobs whose content is stored on disk, rather than in the database
+ * @return string
  */
 function qa_db_count_blobs_on_disk()
 {
@@ -455,7 +460,7 @@ function qa_db_count_blobs_on_disk()
 
 /**
  * Return the id and format of the first blob whose content is stored on disk starting from $startblobid
- * @param $startblobid
+ * @param int $startblobid
  * @return array|null
  */
 function qa_db_get_next_blob_on_disk($startblobid)