PHPDoc update in app/q-list, app/recalc, db/options and db/votes

qa-include/app/q-list.php

@@ -37,21 +37,21 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
  * page has an RSS feed whose URL uses that prefix. If there are no links to other pages, $suggest
  * is used to suggest what the user should do. The $pagelinkparams are passed through to
  * qa_html_page_links(...) which creates links for page 2, 3, etc..
- * @param $questions
- * @param $pagesize
- * @param $start
- * @param $count
- * @param $sometitle
- * @param $nonetitle
- * @param $navcategories
- * @param $categoryid
- * @param $categoryqcount
- * @param $categorypathprefix
- * @param $feedpathprefix
- * @param $suggest
- * @param $pagelinkparams
- * @param $categoryparams
- * @param $dummy
+ * @param array $questions
+ * @param int|null $pagesize
+ * @param int $start
+ * @param int|null $count
+ * @param string $sometitle
+ * @param string $nonetitle
+ * @param array $navcategories
+ * @param int|null $categoryid
+ * @param bool $categoryqcount
+ * @param string|null $categorypathprefix
+ * @param string|null $feedpathprefix
+ * @param string $suggest
+ * @param array|null $pagelinkparams
+ * @param array|null$categoryparams
+ * @param null $dummy
  * @return array
  */
 function qa_q_list_page_content($questions, $pagesize, $start, $count, $sometitle, $nonetitle,
@@ -153,8 +153,8 @@ function qa_q_list_page_content($questions, $pagesize, $start, $count, $sometitl
 
 /**
  * Return the sub navigation structure common to question listing pages
- * @param $sort
- * @param $categoryslugs
+ * @param string $sort
+ * @param array|null $categoryslugs
  * @return array
  */
 function qa_qs_sub_navigation($sort, $categoryslugs)
@@ -210,8 +210,8 @@ function qa_qs_sub_navigation($sort, $categoryslugs)
 
 /**
  * Return the sub navigation structure common to unanswered pages
- * @param $by
- * @param $categoryslugs
+ * @param string $by
+ * @param array|null $categoryslugs
  * @return array
  */
 function qa_unanswered_sub_navigation($by, $categoryslugs)

qa-include/app/recalc.php

@@ -78,7 +78,7 @@ require_once QA_INCLUDE_DIR . 'app/post-update.php';
 /**
  * Advance the recalculation operation represented by $state by a single step.
  * $state can also be the name of a recalculation operation on its own.
- * @param $state
+ * @param string $state
  * @return bool
  */
 function qa_recalc_perform_step(&$state)
@@ -574,8 +574,8 @@ function qa_recalc_perform_step(&$state)
 
 /**
  * Change the $state to represent the beginning of a new $operation
- * @param $state
- * @param $operation
+ * @param string $state
+ * @param string $operation
  */
 function qa_recalc_transition(&$state, $operation)
 {
@@ -589,7 +589,7 @@ function qa_recalc_transition(&$state, $operation)
 
 /**
  * Return how many steps there will be in recalculation $operation
- * @param $operation
+ * @param string $operation
  * @return int
  */
 function qa_recalc_stage_length($operation)
@@ -664,11 +664,9 @@ function qa_recalc_stage_length($operation)
 
 /**
  * Return the translated language ID string replacing the progress and total in it.
- * @access private
  * @param string $langId Language string ID that contains 2 placeholders (^1 and ^2)
  * @param int $progress Amount of processed elements
  * @param int $total Total amount of elements
- *
  * @return string Returns the language string ID with their placeholders replaced with
  * the formatted progress and total numbers
  */
@@ -683,7 +681,7 @@ function qa_recalc_progress_lang($langId, $progress, $total)
 
 /**
  * Return a string which gives a user-viewable version of $state
- * @param $state
+ * @param string $state
  * @return string
  */
 function qa_recalc_get_message($state)

qa-include/db/options.php

@@ -27,8 +27,8 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Set option $name to $value in the database
- * @param $name
- * @param $value
+ * @param string $name
+ * @param string $value
  */
 function qa_db_set_option($name, $value)
 {

qa-include/db/votes.php

@@ -27,9 +27,9 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Set the vote for $userid on $postid to $vote in the database
- * @param $postid
- * @param $userid
- * @param $vote
+ * @param int $postid
+ * @param mixed $userid
+ * @param int $vote
  */
 function qa_db_uservote_set($postid, $userid, $vote)
 {
@@ -44,9 +44,9 @@ function qa_db_uservote_set($postid, $userid, $vote)
 
 /**
  * Get the vote for $userid on $postid from the database (or NULL if none)
- * @param $postid
- * @param $userid
- * @return mixed|null
+ * @param int $postid
+ * @param mixed $userid
+ * @return string|null
  */
 function qa_db_uservote_get($postid, $userid)
 {
@@ -59,13 +59,13 @@ function qa_db_uservote_get($postid, $userid)
 
 /**
  * Set the flag for $userid on $postid to $flag (true or false) in the database
- * @param $postid
- * @param $userid
- * @param $flag
+ * @param int $postid
+ * @param mixed $userid
+ * @param bool $flag
  */
 function qa_db_userflag_set($postid, $userid, $flag)
 {
-	$flag = $flag ? 1 : 0;
+	$flag = (int)$flag;
 
 	qa_db_query_sub(
 		'INSERT INTO ^uservotes (postid, userid, vote, flag) VALUES (#, #, 0, #) ON DUPLICATE KEY UPDATE flag=#',
@@ -76,7 +76,7 @@ function qa_db_userflag_set($postid, $userid, $flag)
 
 /**
  * Clear all flags for $postid in the database
- * @param $postid
+ * @param int $postid
  */
 function qa_db_userflags_clear_all($postid)
 {
@@ -89,7 +89,7 @@ function qa_db_userflags_clear_all($postid)
 
 /**
  * Recalculate the cached count of upvotes, downvotes and netvotes for $postid in the database
- * @param $postid
+ * @param int $postid
  */
 function qa_db_post_recount_votes($postid)
 {
@@ -104,7 +104,7 @@ function qa_db_post_recount_votes($postid)
 
 /**
  * Recalculate the cached count of flags for $postid in the database
- * @param $postid
+ * @param int $postid
  */
 function qa_db_post_recount_flags($postid)
 {
@@ -119,7 +119,7 @@ function qa_db_post_recount_flags($postid)
 
 /**
  * Returns all non-zero votes on post $postid from the database as an array of [userid] => [vote]
- * @param $postid
+ * @param int $postid
  * @return array
  */
 function qa_db_uservote_post_get($postid)
@@ -133,7 +133,7 @@ function qa_db_uservote_post_get($postid)
 
 /**
  * Returns all the postids from the database for posts that $userid has voted on or flagged
- * @param $userid
+ * @param mixed $userid
  * @return array
  */
 function qa_db_uservoteflag_user_get($userid)
@@ -147,7 +147,7 @@ function qa_db_uservoteflag_user_get($userid)
 
 /**
  * Return information about all the non-zero votes and/or flags on the posts in postids, including user handles for internal user management
- * @param $postids
+ * @param array $postids
  * @return array
  */
 function qa_db_uservoteflag_posts_get($postids)
@@ -168,7 +168,6 @@ function qa_db_uservoteflag_posts_get($postids)
 
 /**
  * Remove all votes assigned to a post that had been cast by the owner of the post.
- *
  * @param int $postid The post ID from which the owner's votes will be removed.
  */
 function qa_db_uservote_remove_own($postid)