Merge pull request #734 from pupi1985/patch-122

Add data types to PHPDocs

qa-include/app/blobs.php

@@ -27,9 +27,9 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Return the URL which will output $blobid from the database when requested, $absolute or relative
- * @param $blobid
+ * @param string $blobid
  * @param bool $absolute
- * @return mixed|string
+ * @return string
  */
 function qa_get_blob_url($blobid, $absolute = false)
 {
@@ -41,8 +41,8 @@ function qa_get_blob_url($blobid, $absolute = false)
 
 /**
  * Return the full path to the on-disk directory for blob $blobid (subdirectories are named by the first 3 digits of $blobid)
- * @param $blobid
- * @return mixed|string
+ * @param string $blobid
+ * @return string
  */
 function qa_get_blob_directory($blobid)
 {
@@ -54,9 +54,9 @@ function qa_get_blob_directory($blobid)
 
 /**
  * Return the full page and filename of blob $blobid which is in $format ($format is used as the file name suffix e.g. .jpg)
- * @param $blobid
- * @param $format
- * @return mixed|string
+ * @param string $blobid
+ * @param string $format
+ * @return string
  */
 function qa_get_blob_filename($blobid, $format)
 {
@@ -69,13 +69,13 @@ function qa_get_blob_filename($blobid, $format)
 /**
  * Create a new blob (storing the content in the database or on disk as appropriate) with $content and $format, returning its blobid.
  * Pass the original name of the file uploaded in $sourcefilename and the $userid, $cookieid and $ip of the user creating it
- * @param $content
- * @param $format
- * @param $sourcefilename
- * @param $userid
- * @param $cookieid
- * @param $ip
- * @return mixed|null|string
+ * @param string $content
+ * @param string $format
+ * @param string|null $sourcefilename
+ * @param mixed|null $userid
+ * @param string|null $cookieid
+ * @param string $ip
+ * @return string
  */
 function qa_create_blob($content, $format, $sourcefilename = null, $userid = null, $cookieid = null, $ip = null)
 {
@@ -97,10 +97,10 @@ function qa_create_blob($content, $format, $sourcefilename = null, $userid = nul
 
 /**
  * Write the on-disk file for blob $blobid with $content and $format. Returns true if the write succeeded, false otherwise.
- * @param $blobid
- * @param $content
- * @param $format
- * @return bool|mixed
+ * @param string $blobid
+ * @param string $content
+ * @param string $format
+ * @return bool
  */
 function qa_write_blob_file($blobid, $content, $format)
 {
@@ -130,8 +130,8 @@ function qa_write_blob_file($blobid, $content, $format)
 
 /**
  * Retrieve blob $blobid from the database, reading the content from disk if appropriate
- * @param $blobid
- * @return array|mixed|null
+ * @param string $blobid
+ * @return array
  */
 function qa_read_blob($blobid)
 {
@@ -150,9 +150,9 @@ function qa_read_blob($blobid)
 
 /**
  * Read the content of blob $blobid in $format from disk. On failure, it will return false.
- * @param $blobid
- * @param $format
- * @return mixed|null|string
+ * @param string $blobid
+ * @param string $format
+ * @return false|string|null
  */
 function qa_read_blob_file($blobid, $format)
 {
@@ -168,7 +168,7 @@ function qa_read_blob_file($blobid, $format)
 
 /**
  * Delete blob $blobid from the database, and remove the on-disk file if appropriate
- * @param $blobid
+ * @param string $blobid
  * @return mixed
  */
 function qa_delete_blob($blobid)
@@ -190,8 +190,8 @@ function qa_delete_blob($blobid)
 
 /**
  * Delete the on-disk file for blob $blobid in $format
- * @param $blobid
- * @param $format
+ * @param string $blobid
+ * @param string $format
  * @return mixed
  */
 function qa_delete_blob_file($blobid, $format)
@@ -204,8 +204,8 @@ function qa_delete_blob_file($blobid, $format)
 
 /**
  * Check if blob $blobid exists
- * @param $blobid
- * @return bool|mixed
+ * @param string $blobid
+ * @return bool
  */
 function qa_blob_exists($blobid)
 {

qa-include/app/captcha.php

@@ -38,8 +38,8 @@ function qa_captcha_available()
 
 /**
  * Return an HTML string explaining $captchareason (from qa_user_captcha_reason()) to the user about why they are seeing a captcha
- * @param $captchareason
- * @return mixed|null|string
+ * @param string $captchareason
+ * @return string|null
  */
 function qa_captcha_reason_note($captchareason)
 {
@@ -66,10 +66,10 @@ function qa_captcha_reason_note($captchareason)
 /**
  * Prepare $qa_content for showing a captcha, adding the element to $fields, given previous $errors, and a $note to display.
  * Returns JavaScript required to load CAPTCHA when field is shown by user (e.g. clicking comment button).
- * @param $qa_content
- * @param $fields
- * @param $errors
- * @param $note
+ * @param array $qa_content
+ * @param array $fields
+ * @param array $errors
+ * @param string $note
  * @return string
  */
 function qa_set_up_captcha_field(&$qa_content, &$fields, $errors, $note = null)
@@ -105,7 +105,7 @@ function qa_set_up_captcha_field(&$qa_content, &$fields, $errors, $note = null)
 
 /**
  * Check if captcha is submitted correctly, and if not, set $errors['captcha'] to a descriptive string.
- * @param $errors
+ * @param array $errors
  * @return bool
  */
 function qa_captcha_validate_post(&$errors)

qa-include/app/cookies.php

@@ -27,6 +27,7 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Return the user identification cookie sent by the browser for this page request, or null if none
+ * @return string|null
  */
 function qa_cookie_get()
 {
@@ -39,6 +40,7 @@ function qa_cookie_get()
 /**
  * Return user identification cookie sent by browser if valid, or create a new one if not.
  * Either way, extend for another year (this is used when an anonymous post is created)
+ * @return string
  */
 function qa_cookie_get_create()
 {
@@ -63,8 +65,8 @@ function qa_cookie_get_create()
 /**
  * Called after a database write $action performed by a user identified by $cookieid,
  * relating to $questionid, $answerid and/or $commentid
- * @param $cookieid
- * @param $action
+ * @param string $cookieid
+ * @param string $action
  */
 function qa_cookie_report_action($cookieid, $action)
 {

qa-include/app/emails.php

@@ -24,6 +24,7 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 	exit;
 }
 
+use Q2A\Exceptions\FatalErrorException;
 use Q2A\Notifications\Email;
 use Q2A\Notifications\Mailer;
 use Q2A\Notifications\Status as NotifyStatus;
@@ -44,21 +45,22 @@ function qa_suspend_notifications($suspend = true)
  * Send email to person with $userid and/or $email and/or $handle (null/invalid values are ignored or retrieved from
  * user database as appropriate). Email uses $subject and $body, after substituting each key in $subs with its
  * corresponding value, plus applying some standard substitutions such as ^site_title, ^site_url, ^handle and ^email.
- * @param $userid
- * @param $email
- * @param $handle
- * @param $subject
- * @param $body
- * @param $subs
- * @param bool $html
- * @return bool
+ * If notifications are suspended, then a null value is returned.
+ * @param mixed $userid
+ * @param string $email
+ * @param string $handle
+ * @param string $subject
+ * @param string $body
+ * @param array $subs
+ * @param bool|false $html
+ * @return bool|null
  */
 function qa_send_notification($userid, $email, $handle, $subject, $body, $subs, $html = false)
 {
 	if (qa_to_override(__FUNCTION__)) { $args=func_get_args(); return qa_call_override(__FUNCTION__, $args); }
 
 	if (NotifyStatus::isSuspended()) {
-		return;
+		return null;
 	}
 
 	if ($userid) {
@@ -74,8 +76,9 @@ function qa_send_notification($userid, $email, $handle, $subject, $body, $subs,
 /**
  * Send the email based on the $params array - the following keys are required (some can be empty): fromemail,
  * fromname, toemail, toname, subject, body, html
- * @param $params
+ * @param array $params
  * @return bool
+ * @throws phpmailerException
  */
 function qa_send_email($params)
 {

qa-include/app/events.php

@@ -33,12 +33,12 @@ require_once QA_INCLUDE_DIR . 'app/updates.php';
  * 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. This will add an event to $questionid's and $lastuserid's streams. If
  * $otheruserid is set, it will also add an notification-style event for that user, unless they are the one who did it.
- * @param $questionid
- * @param $lastpostid
- * @param $updatetype
- * @param $lastuserid
- * @param $otheruserid
- * @param $timestamp
+ * @param int $questionid
+ * @param int $lastpostid
+ * @param string $updatetype
+ * @param mixed $lastuserid
+ * @param mixed|null $otheruserid
+ * @param int|null $timestamp
  */
 function qa_create_event_for_q_user($questionid, $lastpostid, $updatetype, $lastuserid, $otheruserid = null, $timestamp = null)
 {
@@ -57,11 +57,11 @@ function qa_create_event_for_q_user($questionid, $lastpostid, $updatetype, $last
  * being created with those tags or having one of those tags added afterwards). The event of type $updatetype relates
  * to the question $questionid, and was caused by $lastuserid. Pass a unix $timestamp for the event time or leave as
  * null to use now.
- * @param $tagstring
- * @param $questionid
- * @param $updatetype
- * @param $lastuserid
- * @param $timestamp
+ * @param string $tagstring
+ * @param int $questionid
+ * @param string $updatetype
+ * @param mixed $lastuserid
+ * @param int $timestamp
  */
 function qa_create_event_for_tags($tagstring, $questionid, $updatetype, $lastuserid, $timestamp = null)
 {
@@ -80,11 +80,11 @@ function qa_create_event_for_tags($tagstring, $questionid, $updatetype, $lastuse
  * that category or being moved to it later on), along with all of its ancestor categories. The event of type
  * $updatetype relates to the question $questionid, and was caused by $lastuserid. Pass a unix $timestamp for the event
  * time or leave as null to use now.
- * @param $categoryid
- * @param $questionid
- * @param $updatetype
- * @param $lastuserid
- * @param $timestamp
+ * @param int|null $categoryid
+ * @param int $questionid
+ * @param string $updatetype
+ * @param mixed $lastuserid
+ * @param int|null $timestamp
  */
 function qa_create_event_for_category($categoryid, $questionid, $updatetype, $lastuserid, $timestamp = null)
 {

qa-include/app/favorites.php

@@ -84,8 +84,8 @@ function qa_user_favorite_set($userid, $handle, $cookieid, $entitytype, $entityi
 /**
  * Returns content to set in $qa_content['q_list'] for a user's favorite $questions. Pre-generated
  * user HTML in $usershtml.
- * @param $questions
- * @param $usershtml
+ * @param array $questions
+ * @param array $usershtml
  * @return array
  */
 function qa_favorite_q_list_view($questions, $usershtml)
@@ -118,8 +118,8 @@ function qa_favorite_q_list_view($questions, $usershtml)
 /**
  * Returns content to set in $qa_content['ranking_users'] for a user's favorite $users. Pre-generated
  * user HTML in $usershtml.
- * @param $users
- * @param $usershtml
+ * @param array $users
+ * @param array $usershtml
  * @return array|null
  */
 function qa_favorite_users_view($users, $usershtml)
@@ -154,7 +154,7 @@ function qa_favorite_users_view($users, $usershtml)
 
 /**
  * Returns content to set in $qa_content['ranking_tags'] for a user's favorite $tags.
- * @param $tags
+ * @param array $tags
  * @return array
  */
 function qa_favorite_tags_view($tags)
@@ -181,7 +181,7 @@ function qa_favorite_tags_view($tags)
 
 /**
  * Returns content to set in $qa_content['nav_list_categories'] for a user's favorite $categories.
- * @param $categories
+ * @param array $categories
  * @return array
  */
 function qa_favorite_categories_view($categories)

qa-include/app/limits.php

@@ -167,7 +167,7 @@ function qa_is_ip_blocked()
 
 /**
  * Return an array of the clauses within $blockipstring, each of which can contain hyphens or asterisks
- * @param $blockipstring
+ * @param string $blockipstring
  * @return array
  */
 function qa_block_ips_explode($blockipstring)
@@ -216,9 +216,9 @@ function qa_block_ip_match($ip, $blockipclause)
 
 /**
  * Check if IP falls between two others.
- * @param $ip
- * @param $startip
- * @param $endip
+ * @param string $ip
+ * @param string $startip
+ * @param string $endip
  * @return bool
  */
 function qa_ip_between($ip, $startip, $endip)
@@ -294,7 +294,7 @@ function qa_report_write_action($userid, $cookieid, $action, $questionid, $answe
 
 /**
  * Take note for rate limits that a user and/or the requesting IP just performed an action.
- * @param int $userid User performing the action.
+ * @param int|null $userid User performing the action.
  * @param string $action One of the QA_LIMIT_* constants defined above.
  * @return mixed
  */

qa-include/app/mailing.php

@@ -120,10 +120,10 @@ function qa_mailing_perform_step()
 /**
  * Send a single message from the mailing, to $userid with $handle and $email.
  * Pass the user's existing $emailcode if there is one, otherwise a new one will be set up
- * @param $userid
- * @param $handle
- * @param $email
- * @param $emailcode
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $email
+ * @param string $emailcode
  * @return bool
  */
 function qa_mailing_send_one($userid, $handle, $email, $emailcode)
@@ -152,6 +152,7 @@ function qa_mailing_send_one($userid, $handle, $email, $emailcode)
 
 /**
  * Return a message describing current progress in the mailing
+ * @return string|null
  */
 function qa_mailing_progress_message()
 {

qa-include/app/messages.php

@@ -28,10 +28,10 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 /**
  * Returns an HTML string describing the reason why user $fromuserid cannot post on the wall of $touserid who has
  * user flags $touserflags. If there is no such reason the function returns false.
- * @param $fromuserid
- * @param $touserid
- * @param $touserflags
- * @return bool|mixed|string
+ * @param mixed $fromuserid
+ * @param mixed $touserid
+ * @param int $touserflags
+ * @return bool|string
  */
 function qa_wall_error_html($fromuserid, $touserid, $touserflags)
 {
@@ -78,13 +78,13 @@ function qa_wall_error_html($fromuserid, $touserid, $touserflags)
 /**
  * Adds a post to the wall of user $touserid with handle $tohandle, containing $content in $format (e.g. '' for text or 'html')
  * The post is by user $userid with handle $handle, and $cookieid is the user's current cookie (used for reporting the event).
- * @param $userid
- * @param $handle
- * @param $cookieid
- * @param $touserid
- * @param $tohandle
- * @param $content
- * @param $format
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
+ * @param mixed $touserid
+ * @param string $tohandle
+ * @param string $content
+ * @param string $format
  * @return mixed
  */
 function qa_wall_add_post($userid, $handle, $cookieid, $touserid, $tohandle, $content, $format)
@@ -113,10 +113,10 @@ function qa_wall_add_post($userid, $handle, $cookieid, $touserid, $tohandle, $co
 /**
  * Deletes the wall post described in $message (as obtained via qa_db_recent_messages_selectspec()). The deletion was performed
  * by user $userid with handle $handle, and $cookieid is the user's current cookie (all used for reporting the event).
- * @param $userid
- * @param $handle
- * @param $cookieid
- * @param $message
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
+ * @param array $message
  */
 function qa_wall_delete_post($userid, $handle, $cookieid, $message)
 {
@@ -136,9 +136,9 @@ function qa_wall_delete_post($userid, $handle, $cookieid, $message)
  * Return the list of messages in $usermessages (as obtained via qa_db_recent_messages_selectspec()) with additional
  * fields indicating what actions can be performed on them by the current user. The messages were retrieved beginning
  * at offset $start in the database. Currently only 'deleteable' is relevant.
- * @param $usermessages
- * @param $start
- * @return mixed
+ * @param array $usermessages
+ * @param int $start
+ * @return array
  */
 function qa_wall_posts_add_rules($usermessages, $start)
 {
@@ -166,7 +166,7 @@ function qa_wall_posts_add_rules($usermessages, $start)
 /**
  * Returns an element to add to $qa_content['message_list']['messages'] for $message (as obtained via
  * qa_db_recent_messages_selectspec() and then qa_wall_posts_add_rules()).
- * @param $message
+ * @param array $message
  * @return array
  */
 function qa_wall_post_view($message)
@@ -197,8 +197,8 @@ function qa_wall_post_view($message)
 
 /**
  * Returns an element to add to $qa_content['message_list']['messages'] with a link to view all wall posts
- * @param $handle
- * @param $start
+ * @param string $handle
+ * @param int $start
  * @return array
  */
 function qa_wall_view_more_link($handle, $start)
@@ -214,11 +214,11 @@ function qa_wall_view_more_link($handle, $start)
  * Hides the private message described in $message (as obtained via qa_db_messages_inbox_selectspec() or qa_db_messages_outbox_selectspec()).
  * If both sender and receiver have hidden the message, it gets deleted from the database.
  * Note: currently no event is reported here, so $handle/$cookieid are unused.
- * @param $userid
- * @param $handle
- * @param $cookieid
- * @param $message
- * @param $box
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
+ * @param array $message
+ * @param string $box
  */
 function qa_pm_delete($userid, $handle, $cookieid, $message, $box)
 {

qa-include/app/options.php

@@ -43,7 +43,7 @@ define('QA_PERMIT_SUPERS', 0);
 /**
  * Return an array [name] => [value] of settings for each option in $names.
  * If any options are missing from the database, set them to their defaults
- * @param $names
+ * @param array $names
  * @return array
  */
 function qa_get_options($names)
@@ -96,8 +96,8 @@ function qa_get_options($names)
 /**
  * Return the value of option $name if it has already been loaded, otherwise return null
  * (used to prevent a database query if it's not essential for us to know the option value)
- * @param $name
- * @return
+ * @param string $name
+ * @return string
  */
 function qa_opt_if_loaded($name)
 {
@@ -139,7 +139,7 @@ function qa_preload_options()
 
 /**
  * Load the options from the $results of the database selectspecs defined in qa_preload_options()
- * @param $results
+ * @param array $results
  * @return mixed
  */
 function qa_load_options_results($results)
@@ -161,8 +161,8 @@ function qa_load_options_results($results)
 /**
  * Set an option $name to $value (application level) in both cache and database, unless
  * $todatabase=false, in which case set it in the cache only
- * @param $name
- * @param $value
+ * @param string $name
+ * @param mixed|null $value
  * @param bool $todatabase
  * @return mixed
  */
@@ -181,7 +181,7 @@ function qa_set_option($name, $value, $todatabase = true)
 
 /**
  * Reset the options in $names to their defaults
- * @param $names
+ * @param array $names
  * @return mixed
  */
 function qa_reset_options($names)
@@ -196,7 +196,7 @@ function qa_reset_options($names)
 
 /**
  * Return the default value for option $name
- * @param $name
+ * @param string $name
  * @return bool|mixed|string
  */
 function qa_default_option($name)
@@ -561,7 +561,7 @@ function qa_default_site_title()
 /**
  * Return an array of defaults for the $options parameter passed to qa_post_html_fields() and its ilk for posts of $basetype='Q'/'A'/'C'
  * Set $full to true if these posts will be viewed in full, i.e. on a question page rather than a question listing
- * @param $basetype
+ * @param string $basetype
  * @param bool $full
  * @return array|mixed
  */
@@ -601,8 +601,8 @@ function qa_post_html_defaults($basetype, $full = false)
  * Return an array of options for post $post to pass in the $options parameter to qa_post_html_fields() and its ilk. Preferably,
  * call qa_post_html_defaults() previously and pass its output in $defaults, to save excessive recalculation for each item in a
  * list. Set $full to true if these posts will be viewed in full, i.e. on a question page rather than a question listing.
- * @param $post
- * @param $defaults
+ * @param array $post
+ * @param array|null $defaults
  * @param bool $full
  * @return array|mixed|null
  */

qa-include/app/page.php

@@ -227,8 +227,8 @@ function qa_get_request_content()
 
 
 /**
- *    Output the $qa_content via the theme class after doing some pre-processing, mainly relating to Javascript
- * @param $qa_content
+ * Output the $qa_content via the theme class after doing some pre-processing, mainly relating to Javascript
+ * @param array $qa_content
  * @return mixed
  */
 function qa_output_content($qa_content)
@@ -382,7 +382,7 @@ function qa_output_content($qa_content)
 
 /**
  * Update any statistics required by the fields in $qa_content, and return true if something was done
- * @param $qa_content
+ * @param array $qa_content
  * @return bool
  */
 function qa_do_content_stats($qa_content)
@@ -487,7 +487,7 @@ function qa_controller_routing()
 
 /**
  * Sets the template which should be passed to the theme class, telling it which type of page it's displaying
- * @param $template
+ * @param string $template
  */
 function qa_set_template($template)
 {

qa-include/app/post-create.php

@@ -33,10 +33,10 @@ require_once QA_INCLUDE_DIR . 'util/string.php';
 
 /**
  * Return value to store in database combining $notify and $email values entered by user $userid (or null for anonymous)
- * @param $userid
- * @param $notify
- * @param $email
- * @return null|string
+ * @param mixed $userid
+ * @param bool $notify
+ * @param string $email
+ * @return string|null
  */
 function qa_combine_notify_email($userid, $notify, $email)
 {
@@ -48,22 +48,22 @@ function qa_combine_notify_email($userid, $notify, $email)
  * Add a question (application level) - create record, update appropriate counts, index it, send notifications.
  * If question is follow-on from an answer, $followanswer should contain answer database record, otherwise null.
  * See /qa-include/app/posts.php for a higher-level function which is easier to use.
- * @param $followanswer
- * @param $userid
- * @param $handle
- * @param $cookieid
- * @param $title
- * @param $content
- * @param $format
- * @param $text
- * @param $tagstring
- * @param $notify
- * @param $email
- * @param $categoryid
- * @param $extravalue
+ * @param array $followanswer
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
+ * @param string $title
+ * @param string $content
+ * @param string $format
+ * @param string $text
+ * @param string $tagstring
+ * @param bool $notify
+ * @param string $email
+ * @param int|null $categoryid
+ * @param string|null $extravalue
  * @param bool $queued
- * @param $name
- * @return mixed
+ * @param string|null $name
+ * @return int
  */
 function qa_question_create($followanswer, $userid, $handle, $cookieid, $title, $content, $format, $text, $tagstring, $notify, $email,
 	$categoryid = null, $extravalue = null, $queued = false, $name = null)
@@ -113,7 +113,7 @@ function qa_question_create($followanswer, $userid, $handle, $cookieid, $title,
 
 /**
  * Perform various common cached count updating operations to reflect changes in the question whose id is $postid
- * @param $postid
+ * @param int|null $postid
  */
 function qa_update_counts_for_q($postid)
 {
@@ -130,8 +130,8 @@ function qa_update_counts_for_q($postid)
 
 /**
  * Return an array containing the elements of $inarray whose key is in $keys
- * @param $inarray
- * @param $keys
+ * @param array $inarray
+ * @param array $keys
  * @return array
  */
 function qa_array_filter_by_keys($inarray, $keys)
@@ -163,16 +163,16 @@ function qa_suspend_post_indexing($suspend = true)
 /**
  * Add post $postid (which comes under $questionid) of $type (Q/A/C) to the database index, with $title, $text,
  * $tagstring and $categoryid. Calls through to all installed search modules.
- * @param $postid
- * @param $type
- * @param $questionid
- * @param $parentid
- * @param $title
- * @param $content
- * @param $format
- * @param $text
- * @param $tagstring
- * @param $categoryid
+ * @param int $postid
+ * @param string $type
+ * @param int $questionid
+ * @param int $parentid
+ * @param string $title
+ * @param string $content
+ * @param string $format
+ * @param string $text
+ * @param string $tagstring
+ * @param int $categoryid
  */
 function qa_post_index($postid, $type, $questionid, $parentid, $title, $content, $format, $text, $tagstring, $categoryid)
 {
@@ -193,18 +193,18 @@ function qa_post_index($postid, $type, $questionid, $parentid, $title, $content,
  * Add an answer (application level) - create record, update appropriate counts, index it, send notifications.
  * $question should contain database record for the question this is an answer to.
  * See /qa-include/app/posts.php for a higher-level function which is easier to use.
- * @param $userid
- * @param $handle
- * @param $cookieid
- * @param $content
- * @param $format
- * @param $text
- * @param $notify
- * @param $email
- * @param $question
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
+ * @param string $content
+ * @param string $format
+ * @param string $text
+ * @param bool $notify
+ * @param string $email
+ * @param array $question
  * @param bool $queued
- * @param $name
- * @return mixed
+ * @param string|null $name
+ * @return int
  */
 function qa_answer_create($userid, $handle, $cookieid, $content, $format, $text, $notify, $email, $question, $queued = false, $name = null)
 {
@@ -244,7 +244,7 @@ function qa_answer_create($userid, $handle, $cookieid, $content, $format, $text,
 
 /**
  * Perform various common cached count updating operations to reflect changes in an answer of question $questionid
- * @param $questionid
+ * @param int $questionid
  */
 function qa_update_q_counts_for_a($questionid)
 {
@@ -263,20 +263,20 @@ function qa_update_q_counts_for_a($questionid)
  * $commentsfollows should contain database records for all previous comments on the same question or answer,
  * but it can also contain other records that are ignored.
  * See /qa-include/app/posts.php for a higher-level function which is easier to use.
- * @param $userid
- * @param $handle
- * @param $cookieid
- * @param $content
- * @param $format
- * @param $text
- * @param $notify
- * @param $email
- * @param $question
- * @param $parent
- * @param $commentsfollows
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
+ * @param string $content
+ * @param string $format
+ * @param string $text
+ * @param bool $notify
+ * @param string $email
+ * @param array $question
+ * @param array $parent
+ * @param array $commentsfollows
  * @param bool $queued
- * @param $name
- * @return mixed
+ * @param string|null $name
+ * @return int
  */
 function qa_comment_create($userid, $handle, $cookieid, $content, $format, $text, $notify, $email, $question, $parent, $commentsfollows, $queued = false, $name = null)
 {

qa-include/app/posts.php

@@ -49,18 +49,18 @@ require_once QA_INCLUDE_DIR . 'util/string.php';
  * post - either to $email if it is specified and valid, or to the current email address of $userid if $email is '@'.
  * If you're creating a question, the $extravalue parameter will be set as the custom extra field, if not null. For all
  * post types you can specify the $name of the post's author, which is relevant if the $userid is null.
- * @param $type
- * @param $parentid
- * @param $title
- * @param $content
+ * @param string $type
+ * @param int|null $parentid
+ * @param string $title
+ * @param string $content
  * @param string $format
- * @param $categoryid
- * @param $tags
- * @param $userid
- * @param $notify
- * @param $email
- * @param $extravalue
- * @param $name
+ * @param int|null $categoryid
+ * @param array|null $tags
+ * @param mixed|null $userid
+ * @param string|null $notify
+ * @param string|null $email
+ * @param string|null $extravalue
+ * @param string|null $name
  * @return mixed
  */
 function qa_post_create($type, $parentid, $title, $content, $format = '', $categoryid = null, $tags = null, $userid = null,
@@ -105,16 +105,16 @@ function qa_post_create($type, $parentid, $title, $content, $format = '', $categ
  * Change the data stored for post $postid based on any of the $title, $content, $format, $tags, $notify, $email,
  * $extravalue and $name parameters passed which are not null. The meaning of these parameters is the same as for
  * qa_post_create() above. Pass the identify of the user making this change in $byuserid (or null for silent).
- * @param $postid
- * @param $title
- * @param $content
- * @param $format
- * @param $tags
- * @param $notify
- * @param $email
- * @param $byuserid
- * @param $extravalue
- * @param $name
+ * @param int $postid
+ * @param string|null $title
+ * @param string|null $content
+ * @param string $format
+ * @param array|null $tags
+ * @param string|null $notify
+ * @param string|null $email
+ * @param mixed|null $byuserid
+ * @param string|null $extravalue
+ * @param string $name
  */
 function qa_post_set_content($postid, $title, $content, $format = null, $tags = null, $notify = null, $email = null, $byuserid = null, $extravalue = null, $name = null)
 {
@@ -166,9 +166,9 @@ function qa_post_set_content($postid, $title, $content, $format = null, $tags =
  * Change the category of $postid to $categoryid. The category of all related posts (shown together on the same
  * question page) will also be changed. Pass the identify of the user making this change in $byuserid (or null for an
  * anonymous change).
- * @param $postid
- * @param $categoryid
- * @param $byuserid
+ * @param int $postid
+ * @param int $categoryid
+ * @param mixed|null $byuserid
  */
 function qa_post_set_category($postid, $categoryid, $byuserid = null)
 {
@@ -189,9 +189,9 @@ function qa_post_set_category($postid, $categoryid, $byuserid = null)
 /**
  * Set the selected best answer of $questionid to $answerid (or to none if $answerid is null). Pass the identify of the
  * user in $byuserid (or null for an anonymous change).
- * @param $questionid
- * @param $answerid
- * @param $byuserid
+ * @param int $questionid
+ * @param int|null $answerid
+ * @param mixed|null $byuserid
  */
 function qa_post_set_selchildid($questionid, $answerid, $byuserid = null)
 {
@@ -210,11 +210,11 @@ function qa_post_set_selchildid($questionid, $answerid, $byuserid = null)
  * Close $questionid if $closed is true, otherwise reopen it. If $closed is true, pass either the $originalpostid of
  * the question that it is a duplicate of, or a $note to explain why it's closed. Pass the identifier of the user in
  * $byuserid (or null for an anonymous change).
- * @param $questionid
+ * @param int $questionid
  * @param bool $closed
- * @param $originalpostid
- * @param $note
- * @param $byuserid
+ * @param int|null $originalpostid
+ * @param string|null $note
+ * @param mixed|null $byuserid
  */
 function qa_post_set_closed($questionid, $closed = true, $originalpostid = null, $note = null, $byuserid = null)
 {
@@ -251,9 +251,9 @@ function qa_post_is_closed(array $question)
  * Hide $postid if $hidden is true, otherwise show the post. Pass the identify of the user making this change in
  * $byuserid (or null for a silent change).
  * @deprecated Replaced by qa_post_set_status.
- * @param $postid
+ * @param int $postid
  * @param bool $hidden
- * @param $byuserid
+ * @param mixed|null $byuserid
  */
 function qa_post_set_hidden($postid, $hidden = true, $byuserid = null)
 {
@@ -264,9 +264,9 @@ function qa_post_set_hidden($postid, $hidden = true, $byuserid = null)
 /**
  * Change the status of $postid to $status, which should be one of the QA_POST_STATUS_* constants defined in
  * /qa-include/app/post-update.php. Pass the identify of the user making this change in $byuserid (or null for a silent change).
- * @param $postid
- * @param $status
- * @param $byuserid
+ * @param int $postid
+ * @param int $status
+ * @param mixed|null $byuserid
  */
 function qa_post_set_status($postid, $status, $byuserid = null)
 {
@@ -298,8 +298,8 @@ function qa_post_set_status($postid, $status, $byuserid = null)
 
 /**
  * Set the created date of $postid to $created, which is a unix timestamp.
- * @param $postid
- * @param $created
+ * @param int $postid
+ * @param int $created
  */
 function qa_post_set_created($postid, $created)
 {
@@ -321,7 +321,7 @@ function qa_post_set_created($postid, $created)
 
 /**
  * Delete $postid from the database, hiding it first if appropriate.
- * @param $postid
+ * @param int $postid
  */
 function qa_post_delete($postid)
 {
@@ -365,9 +365,9 @@ function qa_post_delete($postid)
 
 /**
  * Return the full information from the database for $postid in an array.
- * @param $postid
- * @param $requiredbasetypes
- * @return array|mixed
+ * @param int $postid
+ * @param string|null $requiredbasetypes
+ * @return array
  */
 function qa_post_get_full($postid, $requiredbasetypes = null)
 {
@@ -387,8 +387,8 @@ function qa_post_get_full($postid, $requiredbasetypes = null)
  * Return the handle corresponding to $userid, unless it is null in which case return null.
  *
  * @deprecated Deprecated from 1.7; use `qa_userid_to_handle($userid)` instead.
- * @param $userid
- * @return mixed|null
+ * @param mixed $userid
+ * @return string|null
  */
 function qa_post_userid_to_handle($userid)
 {
@@ -398,8 +398,8 @@ function qa_post_userid_to_handle($userid)
 
 /**
  * Return the textual rendition of $content in $format (used for indexing).
- * @param $content
- * @param $format
+ * @param string $content
+ * @param string $format
  * @return string
  */
 function qa_post_content_to_text($content, $format)
@@ -415,8 +415,8 @@ function qa_post_content_to_text($content, $format)
 
 /**
  * Return tagstring to store in the database based on $tags as an array or a comma-separated string.
- * @param $tags
- * @return mixed|string
+ * @param array|string $tags
+ * @return string
  */
 function qa_post_tags_to_tagstring($tags)
 {
@@ -429,7 +429,7 @@ function qa_post_tags_to_tagstring($tags)
 
 /**
  * Return the full database records for all answers to question $questionid
- * @param $questionid
+ * @param int $questionid
  * @return array
  */
 function qa_post_get_question_answers($questionid)
@@ -449,7 +449,7 @@ function qa_post_get_question_answers($questionid)
 
 /**
  * Return the full database records for all comments or follow-on questions for question $questionid or its answers
- * @param $questionid
+ * @param int $questionid
  * @return array
  */
 function qa_post_get_question_commentsfollows($questionid)
@@ -477,8 +477,8 @@ function qa_post_get_question_commentsfollows($questionid)
 
 /**
  * Return the full database record for the post which closed $questionid, if there is any
- * @param $questionid
- * @return array|mixed
+ * @param int $questionid
+ * @return array|null
  */
 function qa_post_get_question_closepost($questionid)
 {
@@ -488,7 +488,7 @@ function qa_post_get_question_closepost($questionid)
 
 /**
  * Return the full database records for all comments or follow-on questions for answer $answerid
- * @param $answerid
+ * @param int $answerid
  * @return array
  */
 function qa_post_get_answer_commentsfollows($answerid)
@@ -508,8 +508,8 @@ function qa_post_get_answer_commentsfollows($answerid)
 
 /**
  * Return $parent if it's the database record for a question, otherwise return the database record for its parent
- * @param $parent
- * @return array|mixed
+ * @param array $parent
+ * @return array
  */
 function qa_post_parent_to_question($parent)
 {

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/app/search.php

@@ -30,13 +30,13 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
  * to get absolute URLs for the results and $fullcontent if the results should include full post content. This calls
  * through to the chosen search module, and performs all the necessary post-processing to supplement the results for
  * display online or in an RSS feed.
- * @param $query
- * @param $start
- * @param $count
- * @param $userid
- * @param $absoluteurls
- * @param $fullcontent
- * @return
+ * @param string $query
+ * @param int $start
+ * @param int $count
+ * @param mixed $userid
+ * @param bool $absoluteurls
+ * @param bool $fullcontent
+ * @return array
  */
 function qa_get_search_results($query, $start, $count, $userid, $absoluteurls, $fullcontent)
 {

qa-include/app/upload.php

@@ -55,12 +55,12 @@ function qa_get_max_upload_size()
  * 'height' => if an image, the height in pixels of the blob created (after possible scaling)
  * 'blobid' => the blobid that was created (if there was no error)
  * 'bloburl' => the url that can be used to view/download the created blob (if there was no error)
- * @param $localfilename
- * @param $sourcefilename
- * @param $maxfilesize
+ * @param string $localfilename
+ * @param string $sourcefilename
+ * @param int|null $maxfilesize
  * @param bool $onlyimage
- * @param $imagemaxwidth
- * @param $imagemaxheight
+ * @param int|null $imagemaxwidth
+ * @param int|null $imagemaxheight
  * @return array
  */
 function qa_upload_file($localfilename, $sourcefilename, $maxfilesize = null, $onlyimage = false, $imagemaxwidth = null, $imagemaxheight = null)
@@ -197,10 +197,10 @@ function qa_upload_file($localfilename, $sourcefilename, $maxfilesize = null, $o
 
 /**
  * In response to a file upload, move the first uploaded file into blob storage. Other parameters are as for qa_upload_file(...)
- * @param $maxfilesize
+ * @param int|null $maxfilesize
  * @param bool $onlyimage
- * @param $imagemaxwidth
- * @param $imagemaxheight
+ * @param int|null $imagemaxwidth
+ * @param int|null $imagemaxheight
  * @return array
  */
 function qa_upload_file_one($maxfilesize = null, $onlyimage = false, $imagemaxwidth = null, $imagemaxheight = null)

qa-include/app/users-edit.php

@@ -19,6 +19,8 @@
 	More about this license: http://www.question2answer.org/license.php
 */
 
+use Q2A\Exceptions\FatalErrorException;
+
 if (!defined('QA_VERSION')) { // don't allow this page to be requested directly from browser
 	header('Location: ../../');
 	exit;
@@ -39,9 +41,9 @@ if (!defined('QA_NEW_PASSWORD_LEN')){
 /**
  * Return $errors fields for any invalid aspect of user-entered $handle (username) and $email. Works by calling through
  * to all filter modules and also rejects existing values in database unless they belongs to $olduser (if set).
- * @param $handle
- * @param $email
- * @param $olduser
+ * @param string $handle
+ * @param string $email
+ * @param array $olduser
  * @return array
  */
 function qa_handle_email_filter(&$handle, &$email, $olduser = null)
@@ -93,7 +95,7 @@ function qa_handle_email_filter(&$handle, &$email, $olduser = null)
 
 /**
  * Make $handle valid and unique in the database - if $allowuserid is set, allow it to match that user only
- * @param $handle
+ * @param string $handle
  * @return string
  */
 function qa_handle_make_valid($handle)
@@ -139,8 +141,8 @@ function qa_handle_make_valid($handle)
 /**
  * Return an array with a single element (key 'password') if user-entered $password is valid, otherwise an empty array.
  * Works by calling through to all filter modules.
- * @param $password
- * @param $olduser
+ * @param string $password
+ * @param array $olduser
  * @return array
  */
 function qa_password_validate($password, $olduser = null)
@@ -171,9 +173,9 @@ function qa_password_validate($password, $olduser = null)
  * Create a new user (application level) with $email, $password, $handle and $level.
  * Set $confirmed to true if the email address has been confirmed elsewhere.
  * Handles user points, notification and optional email confirmation.
- * @param $email
- * @param $password
- * @param $handle
+ * @param string $email
+ * @param string|null $password
+ * @param string $handle
  * @param int $level
  * @param bool $confirmed
  * @return mixed
@@ -232,7 +234,7 @@ function qa_create_new_user($email, $password, $handle, $level = QA_USER_LEVEL_B
 /**
  * Delete $userid and all their votes and flags. Their posts will become anonymous.
  * Handles recalculations of votes and flags for posts this user has affected.
- * @param $userid
+ * @param mixed $userid
  * @return mixed
  */
 function qa_delete_user($userid)
@@ -265,7 +267,7 @@ function qa_delete_user($userid)
 
 /**
  * Set a new email confirmation code for the user and send it out
- * @param $userid
+ * @param mixed $userid
  * @return mixed
  */
 function qa_send_new_confirm($userid)
@@ -292,10 +294,10 @@ function qa_send_new_confirm($userid)
 /**
  * Set a new email confirmation code for the user and return the corresponding link. If the email code is also sent then that value
  * is used. Otherwise, a new email code is generated
- * @param $userid
- * @param $handle
- * @param $emailcode
- * @return mixed|string
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $emailcode
+ * @return string
  */
 function qa_get_new_confirm_url($userid, $handle, $emailcode = null)
 {
@@ -314,9 +316,9 @@ function qa_get_new_confirm_url($userid, $handle, $emailcode = null)
 
 /**
  * Complete the email confirmation process for the user
- * @param $userid
- * @param $email
- * @param $handle
+ * @param mixed $userid
+ * @param string $email
+ * @param string $handle
  * @return mixed
  */
 function qa_complete_confirm($userid, $email, $handle)
@@ -339,10 +341,10 @@ function qa_complete_confirm($userid, $email, $handle)
 /**
  * Set the user level of user $userid with $handle to $level (one of the QA_USER_LEVEL_* constraints in /qa-include/app/users.php)
  * Pass the previous user level in $oldlevel. Reports the appropriate event, assumes change performed by the logged in user.
- * @param $userid
- * @param $handle
- * @param $level
- * @param $oldlevel
+ * @param mixed $userid
+ * @param string $handle
+ * @param int $level
+ * @param int $oldlevel
  */
 function qa_set_user_level($userid, $handle, $level, $oldlevel)
 {
@@ -368,9 +370,9 @@ function qa_set_user_level($userid, $handle, $level, $oldlevel)
 /**
  * Set the status of user $userid with $handle to blocked if $blocked is true, otherwise to unblocked. Reports the appropriate
  * event, assumes change performed by the logged in user.
- * @param $userid
- * @param $handle
- * @param $blocked
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $blocked
  */
 function qa_set_user_blocked($userid, $handle, $blocked)
 {
@@ -388,7 +390,7 @@ function qa_set_user_blocked($userid, $handle, $blocked)
 
 /**
  * Start the 'I forgot my password' process for $userid, sending reset code
- * @param $userid
+ * @param mixed $userid
  * @return mixed
  */
 function qa_start_reset_user($userid)
@@ -415,9 +417,8 @@ function qa_start_reset_user($userid)
 
 /**
  * Successfully finish the 'I forgot my password' process for $userid, sending new password
- *
  * @deprecated This function has been replaced by qa_finish_reset_user since Q2A 1.8
- * @param $userid
+ * @param mixed $userid
  * @return mixed
  */
 function qa_complete_reset_user($userid)
@@ -454,7 +455,7 @@ function qa_complete_reset_user($userid)
  * Successfully finish the 'I forgot my password' process for $userid, cleaning the emailcode field and logging in the user
  * @param mixed $userId The userid identifiying the user who will have the password reset
  * @param string $newPassword The new password for the user
- * @return void
+ * @return mixed
  */
 function qa_finish_reset_user($userId, $newPassword)
 {
@@ -501,9 +502,9 @@ function qa_logged_in_user_flush()
 
 /**
  * Set the avatar of $userid to the image in $imagedata, and remove $oldblobid from the database if not null
- * @param $userid
- * @param $imagedata
- * @param $oldblobid
+ * @param mixed $userid
+ * @param string $imagedata
+ * @param string $oldblobid
  * @return bool
  */
 function qa_set_user_avatar($userid, $imagedata, $oldblobid = null)

qa-include/app/votes.php

@@ -28,11 +28,11 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 /**
  * Check if $userid can vote on $post, on the page $topage.
  * Return an HTML error to display if there was a problem, or false if it's OK.
- * @param $post
- * @param $vote
- * @param $userid
- * @param $topage
- * @return bool|mixed|string
+ * @param array $post
+ * @param int $vote
+ * @param mixed $userid
+ * @param string $topage
+ * @return bool|string
  */
 function qa_vote_error_html($post, $vote, $userid, $topage)
 {
@@ -106,12 +106,12 @@ function qa_vote_error_html($post, $vote, $userid, $topage)
 /**
  * Actually set (application level) the $vote (-1/0/1) by $userid (with $handle and $cookieid) on $postid.
  * Handles user points, recounting and event reports as appropriate.
- * @param $post
- * @param $userid
- * @param $handle
- * @param $cookieid
- * @param $vote
- * @return void
+ * @param array $post
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
+ * @param int $vote
+ * @return mixed
  */
 function qa_vote_set($post, $userid, $handle, $cookieid, $vote)
 {
@@ -178,10 +178,10 @@ function qa_vote_set($post, $userid, $handle, $cookieid, $vote)
 /**
  * Check if $userid can flag $post, on the page $topage.
  * Return an HTML error to display if there was a problem, or false if it's OK.
- * @param $post
- * @param $userid
- * @param $topage
- * @return bool|mixed|string
+ * @param array $post
+ * @param mixed $userid
+ * @param string $topage
+ * @return bool|string|array
  */
 function qa_flag_error_html($post, $userid, $topage)
 {
@@ -228,11 +228,11 @@ function qa_flag_error_html($post, $userid, $topage)
  * Set (application level) a flag by $userid (with $handle and $cookieid) on $oldpost which belongs to $question.
  * Handles recounting, admin notifications and event reports as appropriate.
  * Returns true if the post should now be hidden because it has accumulated enough flags.
- * @param $oldpost
- * @param $userid
- * @param $handle
- * @param $cookieid
- * @param $question
+ * @param array $oldpost
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
+ * @param array $question
  * @return bool
  */
 function qa_flag_set_tohide($oldpost, $userid, $handle, $cookieid, $question)
@@ -278,10 +278,10 @@ function qa_flag_set_tohide($oldpost, $userid, $handle, $cookieid, $question)
 /**
  * Clear (application level) a flag on $oldpost by $userid (with $handle and $cookieid).
  * Handles recounting and event reports as appropriate.
- * @param $oldpost
- * @param $userid
- * @param $handle
- * @param $cookieid
+ * @param array $oldpost
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
  * @return mixed
  */
 function qa_flag_clear($oldpost, $userid, $handle, $cookieid)
@@ -320,10 +320,10 @@ function qa_flag_clear($oldpost, $userid, $handle, $cookieid)
 /**
  * Clear (application level) all flags on $oldpost by $userid (with $handle and $cookieid).
  * Handles recounting and event reports as appropriate.
- * @param $oldpost
- * @param $userid
- * @param $handle
- * @param $cookieid
+ * @param array $oldpost
+ * @param mixed $userid
+ * @param string $handle
+ * @param string $cookieid
  * @return mixed
  */
 function qa_flags_clear_all($oldpost, $userid, $handle, $cookieid)

qa-include/db/blobs.php

@@ -27,13 +27,13 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Create a new blob in the database with $content and $format, other fields as provided
- * @param $content
- * @param $format
- * @param $sourcefilename
- * @param $userid
- * @param $cookieid
- * @param $ip
- * @return mixed|null|string
+ * @param string $content
+ * @param string $format
+ * @param string|null $sourcefilename
+ * @param mixed|null $userid
+ * @param string|null $cookieid
+ * @param string|null $ip
+ * @return mixed|string|null
  */
 function qa_db_blob_create($content, $format, $sourcefilename = null, $userid = null, $cookieid = null, $ip = null)
 {
@@ -59,8 +59,8 @@ function qa_db_blob_create($content, $format, $sourcefilename = null, $userid =
 
 /**
  * Get the information about blob $blobid from the database
- * @param $blobid
- * @return array|mixed|null
+ * @param string $blobid
+ * @return array|null
  */
 function qa_db_blob_read($blobid)
 {
@@ -75,8 +75,8 @@ function qa_db_blob_read($blobid)
 
 /**
  * Change the content of blob $blobid in the database to $content (can also be null)
- * @param $blobid
- * @param $content
+ * @param string $blobid
+ * @param string $content
  */
 function qa_db_blob_set_content($blobid, $content)
 {
@@ -89,7 +89,7 @@ function qa_db_blob_set_content($blobid, $content)
 
 /**
  * Delete blob $blobid in the database
- * @param $blobid
+ * @param string $blobid
  * @return mixed
  */
 function qa_db_blob_delete($blobid)
@@ -105,8 +105,8 @@ function qa_db_blob_delete($blobid)
 
 /**
  * Check if blob $blobid exists in the database
- * @param $blobid
- * @return bool|mixed
+ * @param string $blobid
+ * @return bool
  */
 function qa_db_blob_exists($blobid)
 {

qa-include/db/cache.php

@@ -29,9 +29,9 @@ require_once QA_INCLUDE_DIR . 'db/maxima.php';
 
 /**
  * Create (or replace) the item ($type, $cacheid) in the database cache table with $content
- * @param $type
- * @param $cacheid
- * @param $content
+ * @param string $type
+ * @param string $cacheid
+ * @param string $content
  * @return mixed
  */
 function qa_db_cache_set($type, $cacheid, $content)
@@ -53,8 +53,8 @@ function qa_db_cache_set($type, $cacheid, $content)
 
 /**
  * Retrieve the item ($type, $cacheid) from the database cache table
- * @param $type
- * @param $cacheid
+ * @param string $type
+ * @param string $cacheid
  * @return mixed|null
  */
 function qa_db_cache_get($type, $cacheid)

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/favorites.php

@@ -106,9 +106,9 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
  * Add the entity $entitytype with $entityid to the favorites list of $userid. Handles switching streams across from
  * per-user to per-entity based on how many other users have favorited the entity (see long explanation above). If
  * appropriate, it also adds recent events from that entity to the user's event stream.
- * @param $userid
- * @param $entitytype
- * @param $entityid
+ * @param mixed $userid
+ * @param string $entitytype
+ * @param int $entityid
  */
 function qa_db_favorite_create($userid, $entitytype, $entityid)
 {
@@ -186,9 +186,9 @@ function qa_db_favorite_create($userid, $entitytype, $entityid)
 /**
  * Delete the entity $entitytype with $entityid from the favorites list of $userid, removing any corresponding events
  * from the user's stream.
- * @param $userid
- * @param $entitytype
- * @param $entityid
+ * @param mixed $userid
+ * @param string $entitytype
+ * @param int $entityid
  */
 function qa_db_favorite_delete($userid, $entitytype, $entityid)
 {

qa-include/db/hotness.php

@@ -46,9 +46,9 @@ function qa_db_increment_views($postid)
  *
  * @param int $firstpostid First post to recalculate (or only post if $lastpostid is null).
  * @param int $lastpostid Last post in the range to recalculate.
- * @param bool $viewincrement Deprecated - view counter is now incremented separately. Previously, would increment the post's
- *   views and include that in the hotness calculation.
- * @return void
+ * @param bool $viewincrement Deprecated - view counter is now incremented separately. Previously, would increment the
+ * post's views and include that in the hotness calculation.
+ * @return mixed
  */
 function qa_db_hotness_update($firstpostid, $lastpostid = null, $viewincrement = false)
 {

qa-include/db/install.php

@@ -29,6 +29,7 @@ define('QA_DB_VERSION_CURRENT', 67);
 
 /**
  * Return the column type for user ids after verifying it is one of the legal options
+ * @return string
  */
 function qa_db_user_column_type_verify()
 {
@@ -59,6 +60,7 @@ function qa_db_user_column_type_verify()
 /**
  * Return an array of table definitions. For each element of the array, the key is the table name (without prefix)
  * and the value is an array of column definitions, [column name] => [definition]. The column name is omitted for indexes.
+ * @return array
  */
 function qa_db_table_definitions()
 {
@@ -539,7 +541,7 @@ function qa_db_table_definitions()
 
 /**
  * Return array with all values from $array as keys
- * @param $array
+ * @param array $array
  * @return array
  */
 function qa_array_to_keys($array)
@@ -550,7 +552,7 @@ function qa_array_to_keys($array)
 
 /**
  * Return a list of tables missing from the database, [table name] => [column/index definitions]
- * @param $definitions
+ * @param array $definitions
  * @return array
  */
 function qa_db_missing_tables($definitions)
@@ -569,8 +571,8 @@ function qa_db_missing_tables($definitions)
 
 /**
  * Return a list of columns missing from $table in the database, given the full definition set in $definition
- * @param $table
- * @param $definition
+ * @param string $table
+ * @param array $definition
  * @return array
  */
 function qa_db_missing_columns($table, $definition)
@@ -589,6 +591,7 @@ function qa_db_missing_columns($table, $definition)
 
 /**
  * Return the current version of the Q2A database, to determine need for DB upgrades
+ * @return int|null
  */
 function qa_db_get_db_version()
 {
@@ -607,7 +610,7 @@ function qa_db_get_db_version()
 
 /**
  * Set the current version in the database
- * @param $version
+ * @param int $version
  */
 function qa_db_set_db_version($version)
 {
@@ -619,6 +622,7 @@ function qa_db_set_db_version($version)
 
 /**
  * Return a string describing what is wrong with the database, or false if everything is just fine
+ * @return false|string
  */
 function qa_db_check_tables()
 {
@@ -703,8 +707,8 @@ function qa_db_install_tables()
 
 /**
  * Return the SQL command to create a table with $rawname and $definition obtained from qa_db_table_definitions()
- * @param $rawname
- * @param $definition
+ * @param string $rawname
+ * @param array $definition
  * @return string
  */
 function qa_db_create_table_sql($rawname, $definition)
@@ -720,6 +724,7 @@ function qa_db_create_table_sql($rawname, $definition)
 
 /**
  * Return the SQL to create the default entries in the userfields table (before 1.3 these were hard-coded in PHP)
+ * @return string
  */
 function qa_db_default_userfields_sql()
 {
@@ -1629,9 +1634,9 @@ function qa_db_upgrade_tables()
 
 /**
  * Reset the definitions of $columns in $table according to the $definitions array
- * @param $definitions
- * @param $table
- * @param $columns
+ * @param array $definitions
+ * @param string $table
+ * @param array $columns
  */
 function qa_db_upgrade_table_columns($definitions, $table, $columns)
 {
@@ -1646,7 +1651,7 @@ function qa_db_upgrade_table_columns($definitions, $table, $columns)
 
 /**
  * Perform upgrade $query and output progress to the browser
- * @param $query
+ * @param string $query
  */
 function qa_db_upgrade_query($query)
 {
@@ -1657,7 +1662,7 @@ function qa_db_upgrade_query($query)
 
 /**
  * Output $text to the browser (after converting to HTML) and do all we can to get it displayed
- * @param $text
+ * @param string $text
  */
 function qa_db_upgrade_progress($text)
 {

qa-include/db/limits.php

@@ -28,9 +28,9 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 /**
  * Get rate limit information for $action from the database for user $userid and/or IP address $ip, if they're set.
  * Return as an array with the limit type in the key, and a labelled array of the period and count.
- * @param $userid
- * @param $ip
- * @param $action
+ * @param mixed $userid
+ * @param string|null $ip
+ * @param string $action
  * @return array
  */
 function qa_db_limits_get($userid, $ip, $action)
@@ -50,7 +50,7 @@ function qa_db_limits_get($userid, $ip, $action)
 		$arguments[] = $action;
 	}
 
-	if (count($selects)) {
+	if (!empty($selects)) {
 		$query = qa_db_apply_sub(implode(' UNION ALL ', $selects), $arguments);
 		return qa_db_read_all_assoc(qa_db_query_raw($query), 'limitkey');
 
@@ -61,10 +61,10 @@ function qa_db_limits_get($userid, $ip, $action)
 
 /**
  * Increment the database rate limit count for user $userid and $action by $count within $period
- * @param $userid
- * @param $action
- * @param $period
- * @param $count
+ * @param mixed $userid
+ * @param string $action
+ * @param int $period
+ * @param int $count
  */
 function qa_db_limits_user_add($userid, $action, $period, $count)
 {
@@ -78,10 +78,10 @@ function qa_db_limits_user_add($userid, $action, $period, $count)
 
 /**
  * Increment the database rate limit count for IP address $ip and $action by $count within $period
- * @param $ip
- * @param $action
- * @param $period
- * @param $count
+ * @param string $ip
+ * @param string $action
+ * @param int $period
+ * @param int $count
  */
 function qa_db_limits_ip_add($ip, $action, $period, $count)
 {

qa-include/db/messages.php

@@ -28,12 +28,12 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 /**
  * Record a message sent from $fromuserid to $touserid with $content in $format in the database. $public sets whether
  * public (on wall) or private. Return the messageid of the row created.
- * @param $fromuserid
- * @param $touserid
- * @param $content
- * @param $format
+ * @param mixed $fromuserid
+ * @param mixed $touserid
+ * @param string $content
+ * @param string $format
  * @param bool $public
- * @return mixed
+ * @return string
  */
 function qa_db_message_create($fromuserid, $touserid, $content, $format, $public = false)
 {
@@ -48,8 +48,8 @@ function qa_db_message_create($fromuserid, $touserid, $content, $format, $public
 
 /**
  * Hide the message with $messageid, in $box (inbox|outbox) from the user.
- * @param $messageid
- * @param $box
+ * @param int $messageid
+ * @param string $box
  */
 function qa_db_message_user_hide($messageid, $box)
 {
@@ -64,7 +64,7 @@ function qa_db_message_user_hide($messageid, $box)
 
 /**
  * Delete the message with $messageid from the database.
- * @param $messageid
+ * @param int $messageid
  * @param bool $public
  */
 function qa_db_message_delete($messageid, $public = true)
@@ -81,7 +81,7 @@ function qa_db_message_delete($messageid, $public = true)
 
 /**
  * Recalculate the cached count of wall posts for user $userid in the database
- * @param $userid
+ * @param mixed $userid
  */
 function qa_db_user_recount_posts($userid)
 {

qa-include/db/metas.php

@@ -27,9 +27,9 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Set the metadata for user $userid with $key to $value. Keys beginning qa_ are reserved for the Q2A core.
- * @param $userid
- * @param $key
- * @param $value
+ * @param mixed $userid
+ * @param string $key
+ * @param string $value
  */
 function qa_db_usermeta_set($userid, $key, $value)
 {
@@ -39,8 +39,8 @@ function qa_db_usermeta_set($userid, $key, $value)
 
 /**
  * Clear the metadata for user $userid with $key ($key can also be an array of keys)
- * @param $userid
- * @param $key
+ * @param mixed $userid
+ * @param string $key
  */
 function qa_db_usermeta_clear($userid, $key)
 {
@@ -51,8 +51,8 @@ function qa_db_usermeta_clear($userid, $key)
 /**
  * Return the metadata value for user $userid with $key ($key can also be an array of keys in which case this
  * returns an array of metadata key => value).
- * @param $userid
- * @param $key
+ * @param mixed $userid
+ * @param string $key
  * @return array|mixed|null
  */
 function qa_db_usermeta_get($userid, $key)
@@ -63,9 +63,9 @@ function qa_db_usermeta_get($userid, $key)
 
 /**
  * Set the metadata for post $postid with $key to $value. Keys beginning qa_ are reserved for the Q2A core.
- * @param $postid
- * @param $key
- * @param $value
+ * @param int $postid
+ * @param string $key
+ * @param string $value
  */
 function qa_db_postmeta_set($postid, $key, $value)
 {
@@ -75,8 +75,8 @@ function qa_db_postmeta_set($postid, $key, $value)
 
 /**
  * Clear the metadata for post $postid with $key ($key can also be an array of keys)
- * @param $postid
- * @param $key
+ * @param int $postid
+ * @param string $key
  */
 function qa_db_postmeta_clear($postid, $key)
 {
@@ -87,8 +87,8 @@ function qa_db_postmeta_clear($postid, $key)
 /**
  * Return the metadata value for post $postid with $key ($key can also be an array of keys in which case this
  * returns an array of metadata key => value).
- * @param $postid
- * @param $key
+ * @param int $postid
+ * @param string $key
  * @return array|mixed|null
  */
 function qa_db_postmeta_get($postid, $key)
@@ -99,9 +99,9 @@ function qa_db_postmeta_get($postid, $key)
 
 /**
  * Set the metadata for category $categoryid with $key to $value. Keys beginning qa_ are reserved for the Q2A core.
- * @param $categoryid
- * @param $key
- * @param $value
+ * @param int $categoryid
+ * @param string $key
+ * @param string $value
  */
 function qa_db_categorymeta_set($categoryid, $key, $value)
 {
@@ -111,8 +111,8 @@ function qa_db_categorymeta_set($categoryid, $key, $value)
 
 /**
  * Clear the metadata for category $categoryid with $key ($key can also be an array of keys)
- * @param $categoryid
- * @param $key
+ * @param int $categoryid
+ * @param string $key
  */
 function qa_db_categorymeta_clear($categoryid, $key)
 {
@@ -123,8 +123,8 @@ function qa_db_categorymeta_clear($categoryid, $key)
 /**
  * Return the metadata value for category $categoryid with $key ($key can also be an array of keys in which
  * case this returns an array of metadata key => value).
- * @param $categoryid
- * @param $key
+ * @param int $categoryid
+ * @param string $key
  * @return array|mixed|null
  */
 function qa_db_categorymeta_get($categoryid, $key)
@@ -135,9 +135,9 @@ function qa_db_categorymeta_get($categoryid, $key)
 
 /**
  * Set the metadata for tag $tag with $key to $value. Keys beginning qa_ are reserved for the Q2A core.
- * @param $tag
- * @param $key
- * @param $value
+ * @param string $tag
+ * @param string $key
+ * @param string $value
  */
 function qa_db_tagmeta_set($tag, $key, $value)
 {
@@ -147,8 +147,8 @@ function qa_db_tagmeta_set($tag, $key, $value)
 
 /**
  * Clear the metadata for tag $tag with $key ($key can also be an array of keys)
- * @param $tag
- * @param $key
+ * @param string $tag
+ * @param string $key
  */
 function qa_db_tagmeta_clear($tag, $key)
 {
@@ -159,9 +159,9 @@ function qa_db_tagmeta_clear($tag, $key)
 /**
  * Return the metadata value for tag $tag with $key ($key can also be an array of keys in which case this
  * returns an array of metadata key => value).
- * @param $tag
- * @param $key
- * @return array|mixed|null
+ * @param string $tag
+ * @param string $key
+ * @return mixed
  */
 function qa_db_tagmeta_get($tag, $key)
 {
@@ -171,11 +171,11 @@ function qa_db_tagmeta_get($tag, $key)
 
 /**
  * Internal general function to set metadata
- * @param $metatable
- * @param $idcolumn
- * @param $idvalue
- * @param $title
- * @param $content
+ * @param string $metatable
+ * @param string $idcolumn
+ * @param string $idvalue
+ * @param string $title
+ * @param string $content
  */
 function qa_db_meta_set($metatable, $idcolumn, $idvalue, $title, $content)
 {
@@ -189,10 +189,10 @@ function qa_db_meta_set($metatable, $idcolumn, $idvalue, $title, $content)
 
 /**
  * Internal general function to clear metadata
- * @param $metatable
- * @param $idcolumn
- * @param $idvalue
- * @param $title
+ * @param string $metatable
+ * @param string $idcolumn
+ * @param string $idvalue
+ * @param string|array $title
  */
 function qa_db_meta_clear($metatable, $idcolumn, $idvalue, $title)
 {
@@ -214,11 +214,11 @@ function qa_db_meta_clear($metatable, $idcolumn, $idvalue, $title)
 
 /**
  * Internal general function to return metadata
- * @param $metatable
- * @param $idcolumn
- * @param $idvalue
- * @param $title
- * @return array|mixed|null
+ * @param string $metatable
+ * @param string $idcolumn
+ * @param string $idvalue
+ * @param string|array $title
+ * @return mixed
  */
 function qa_db_meta_get($metatable, $idcolumn, $idvalue, $title)
 {

qa-include/db/notices.php

@@ -27,10 +27,10 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Create a notice for $userid with $content in $format and optional $tags (not displayed) and return its noticeid
- * @param $userid
- * @param $content
+ * @param mixed $userid
+ * @param string $content
  * @param string $format
- * @param $tags
+ * @param string|null $tags
  * @return mixed
  */
 function qa_db_usernotice_create($userid, $content, $format = '', $tags = null)
@@ -46,8 +46,8 @@ function qa_db_usernotice_create($userid, $content, $format = '', $tags = null)
 
 /**
  * Delete the notice $notice which belongs to $userid
- * @param $userid
- * @param $noticeid
+ * @param mixed $userid
+ * @param int $noticeid
  */
 function qa_db_usernotice_delete($userid, $noticeid)
 {
@@ -60,7 +60,7 @@ function qa_db_usernotice_delete($userid, $noticeid)
 
 /**
  * Return an array summarizing the notices to be displayed for $userid, including the tags (not displayed)
- * @param $userid
+ * @param mixed $userid
  * @return array
  */
 function qa_db_usernotices_list($userid)

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/points.php

@@ -27,6 +27,7 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Returns an array of option names required to perform calculations in userpoints table
+ * @return mixed
  */
 function qa_db_points_option_names()
 {
@@ -49,6 +50,7 @@ function qa_db_points_option_names()
  * The element 'formula' contains the SQL fragment that calculates the columns value for one or more users,
  * where the ~ symbol within the fragment is substituted for a constraint on which users we are interested in.
  * The element 'multiple' specifies what to multiply each column by to create the final sum in the points column.
+ * @return mixed
  */
 function qa_db_points_calculations()
 {
@@ -156,10 +158,10 @@ function qa_db_points_calculations()
 
 /**
  * Update the userpoints table in the database for $userid and $columns, plus the summary points column.
- * Set $columns to true for all, empty for none, an array for several, or a single value for one.
+ * Set $columns to true for all, false for none, an array for several, or a single value for one.
  * This dynamically builds some fairly crazy looking SQL, but it works, and saves repeat calculations.
- * @param $userid
- * @param $columns
+ * @param mixed $userid
+ * @param bool|string|array $columns
  * @return mixed
  */
 function qa_db_points_update_ifuser($userid, $columns)
@@ -217,8 +219,8 @@ function qa_db_points_update_ifuser($userid, $columns)
 
 /**
  * Set the number of explicit bonus points for $userid to $bonus
- * @param $userid
- * @param $bonus
+ * @param mixed $userid
+ * @param int $bonus
  */
 function qa_db_points_set_bonus($userid, $bonus)
 {

qa-include/db/post-create.php

@@ -27,19 +27,19 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Create a new post in the database and return its ID (based on auto-incrementing)
- * @param $type
- * @param $parentid
- * @param $userid
- * @param $cookieid
- * @param $ip
- * @param $title
- * @param $content
- * @param $format
- * @param $tagstring
- * @param $notify
- * @param $categoryid
- * @param $name
- * @return mixed
+ * @param string $type
+ * @param int $parentid
+ * @param mixed $userid
+ * @param string $cookieid
+ * @param string $ip
+ * @param string $title
+ * @param string $content
+ * @param string $format
+ * @param string $tagstring
+ * @param bool $notify
+ * @param int|null $categoryid
+ * @param string|null $name
+ * @return string
  */
 function qa_db_post_create($type, $parentid, $userid, $cookieid, $ip, $title, $content, $format, $tagstring, $notify, $categoryid = null, $name = null)
 {
@@ -55,8 +55,8 @@ function qa_db_post_create($type, $parentid, $userid, $cookieid, $ip, $title, $c
 
 /**
  * Recalculate the full category path (i.e. columns catidpath1/2/3) for posts from $firstpostid to $lastpostid (if specified)
- * @param $firstpostid
- * @param $lastpostid
+ * @param int $firstpostid
+ * @param int|null $lastpostid
  */
 function qa_db_posts_calc_category_path($firstpostid, $lastpostid = null)
 {
@@ -76,8 +76,8 @@ function qa_db_posts_calc_category_path($firstpostid, $lastpostid = null)
 
 /**
  * Get the full category path (including categoryid) for $postid
- * @param $postid
- * @return array|null
+ * @param int $postid
+ * @return array
  */
 function qa_db_post_get_category_path($postid)
 {
@@ -90,7 +90,7 @@ function qa_db_post_get_category_path($postid)
 
 /**
  * Update the cached number of answers for $questionid in the database, along with the highest netvotes of any of its answers
- * @param $questionid
+ * @param int $questionid
  */
 function qa_db_post_acount_update($questionid)
 {
@@ -105,7 +105,7 @@ function qa_db_post_acount_update($questionid)
 
 /**
  * Recalculate the number of questions for each category in $path retrieved via qa_db_post_get_category_path()
- * @param $path
+ * @param array $path
  */
 function qa_db_category_path_qcount_update($path)
 {
@@ -118,7 +118,7 @@ function qa_db_category_path_qcount_update($path)
 
 /**
  * Update the cached number of questions for category $categoryid in the database, including its subcategories
- * @param $categoryid
+ * @param int|null $categoryid
  */
 function qa_db_ifcategory_qcount_update($categoryid)
 {
@@ -136,12 +136,12 @@ function qa_db_ifcategory_qcount_update($categoryid)
 /**
  * Add rows into the database title index, where $postid contains the words $wordids - this does the same sort
  * of thing as qa_db_posttags_add_post_wordids() in a different way, for no particularly good reason.
- * @param $postid
- * @param $wordids
+ * @param int $postid
+ * @param array $wordids
  */
 function qa_db_titlewords_add_post_wordids($postid, $wordids)
 {
-	if (count($wordids)) {
+	if (!empty($wordids)) {
 		$rowstoadd = array();
 		foreach ($wordids as $wordid)
 			$rowstoadd[] = array($postid, $wordid);
@@ -157,14 +157,14 @@ function qa_db_titlewords_add_post_wordids($postid, $wordids)
 /**
  * Add rows into the database content index, where $postid (of $type, with the antecedent $questionid)
  * has words as per the keys of $wordidcounts, and the corresponding number of those words in the values.
- * @param $postid
- * @param $type
- * @param $questionid
- * @param $wordidcounts
+ * @param int $postid
+ * @param string $type
+ * @param int $questionid
+ * @param array $wordidcounts
  */
 function qa_db_contentwords_add_post_wordidcounts($postid, $type, $questionid, $wordidcounts)
 {
-	if (count($wordidcounts)) {
+	if (!empty($wordidcounts)) {
 		$rowstoadd = array();
 		foreach ($wordidcounts as $wordid => $count)
 			$rowstoadd[] = array($postid, $wordid, $count, $type, $questionid);
@@ -179,12 +179,12 @@ function qa_db_contentwords_add_post_wordidcounts($postid, $type, $questionid, $
 
 /**
  * Add rows into the database index of individual tag words, where $postid contains the words $wordids
- * @param $postid
- * @param $wordids
+ * @param int $postid
+ * @param array $wordids
  */
 function qa_db_tagwords_add_post_wordids($postid, $wordids)
 {
-	if (count($wordids)) {
+	if (!empty($wordids)) {
 		$rowstoadd = array();
 		foreach ($wordids as $wordid)
 			$rowstoadd[] = array($postid, $wordid);
@@ -199,12 +199,12 @@ function qa_db_tagwords_add_post_wordids($postid, $wordids)
 
 /**
  * Add rows into the database index of whole tags, where $postid contains the tags $wordids
- * @param $postid
- * @param $wordids
+ * @param int $postid
+ * @param array $wordids
  */
 function qa_db_posttags_add_post_wordids($postid, $wordids)
 {
-	if (count($wordids)) {
+	if (!empty($wordids)) {
 		qa_db_query_sub(
 			'INSERT INTO ^posttags (postid, wordid, postcreated) SELECT postid, wordid, created FROM ^words, ^posts WHERE postid=# AND wordid IN ($)',
 			$postid, $wordids
@@ -215,12 +215,12 @@ function qa_db_posttags_add_post_wordids($postid, $wordids)
 
 /**
  * Return an array mapping each word in $words to its corresponding wordid in the database
- * @param $words
+ * @param array $words
  * @return array
  */
 function qa_db_word_mapto_ids($words)
 {
-	if (count($words)) {
+	if (!empty($words)) {
 		return qa_db_read_all_assoc(qa_db_query_sub(
 			'SELECT wordid, word FROM ^words WHERE word IN ($)', $words
 		), 'word', 'wordid');
@@ -232,7 +232,7 @@ function qa_db_word_mapto_ids($words)
 
 /**
  * Return an array mapping each word in $words to its corresponding wordid in the database, adding any that are missing
- * @param $words
+ * @param array $words
  * @return array
  */
 function qa_db_word_mapto_ids_add($words)
@@ -245,7 +245,7 @@ function qa_db_word_mapto_ids_add($words)
 			$wordstoadd[] = $word;
 	}
 
-	if (count($wordstoadd)) {
+	if (!empty($wordstoadd)) {
 		qa_db_query_sub('LOCK TABLES ^words WRITE'); // to prevent two requests adding the same word
 
 		$wordtoid = qa_db_word_mapto_ids($words); // map it again in case table content changed before it was locked
@@ -269,7 +269,7 @@ function qa_db_word_mapto_ids_add($words)
 
 /**
  * Update the titlecount column in the database for the words in $wordids, based on how many posts they appear in the title of
- * @param $wordids
+ * @param array $wordids
  */
 function qa_db_word_titlecount_update($wordids)
 {
@@ -284,7 +284,7 @@ function qa_db_word_titlecount_update($wordids)
 
 /**
  * Update the contentcount column in the database for the words in $wordids, based on how many posts they appear in the content of
- * @param $wordids
+ * @param array $wordids
  */
 function qa_db_word_contentcount_update($wordids)
 {
@@ -299,7 +299,7 @@ function qa_db_word_contentcount_update($wordids)
 
 /**
  * Update the tagwordcount column in the database for the individual tag words in $wordids, based on how many posts they appear in the tags of
- * @param $wordids
+ * @param array $wordids
  */
 function qa_db_word_tagwordcount_update($wordids)
 {
@@ -314,7 +314,7 @@ function qa_db_word_tagwordcount_update($wordids)
 
 /**
  * Update the tagcount column in the database for the whole tags in $wordids, based on how many posts they appear as tags of
- * @param $wordids
+ * @param array $wordids
  */
 function qa_db_word_tagcount_update($wordids)
 {

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)

qa-include/db/users.php

@@ -27,9 +27,9 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Return the expected value for the passcheck column given the $password and password $salt
- * @param $password
- * @param $salt
- * @return mixed|string
+ * @param string $password
+ * @param string $salt
+ * @return string
  */
 function qa_db_calc_passcheck($password, $salt)
 {
@@ -41,12 +41,12 @@ function qa_db_calc_passcheck($password, $salt)
 
 /**
  * Create a new user in the database with $email, $password, $handle, privilege $level, and $ip address
- * @param $email
- * @param $password
- * @param $handle
- * @param $level
- * @param $ip
- * @return mixed
+ * @param string $email
+ * @param string|null $password
+ * @param string $handle
+ * @param int $level
+ * @param string $ip
+ * @return string
  */
 function qa_db_user_create($email, $password, $handle, $level, $ip)
 {
@@ -77,7 +77,7 @@ function qa_db_user_create($email, $password, $handle, $level, $ip)
 
 /**
  * Delete user $userid from the database, along with everything they have ever done (to the extent that it's possible)
- * @param $userid
+ * @param mixed $userid
  */
 function qa_db_user_delete($userid)
 {
@@ -101,7 +101,7 @@ function qa_db_user_delete($userid)
 
 /**
  * Return the ids of all users in the database which match $email (should be one or none)
- * @param $email
+ * @param string $email
  * @return array
  */
 function qa_db_user_find_by_email($email)
@@ -115,7 +115,7 @@ function qa_db_user_find_by_email($email)
 
 /**
  * Return the ids of all users in the database which match $handle (=username), should be one or none
- * @param $handle
+ * @param string $handle
  * @return array
  */
 function qa_db_user_find_by_handle($handle)
@@ -129,12 +129,12 @@ function qa_db_user_find_by_handle($handle)
 
 /**
  * Return an array mapping each userid in $userids that can be found to that user's handle
- * @param $userids
+ * @param array $userids
  * @return array
  */
 function qa_db_user_get_userid_handles($userids)
 {
-	if (count($userids)) {
+	if (!empty($userids)) {
 		return qa_db_read_all_assoc(qa_db_query_sub(
 			'SELECT userid, handle FROM ^users WHERE userid IN (#)',
 			$userids
@@ -147,12 +147,12 @@ function qa_db_user_get_userid_handles($userids)
 
 /**
  * Return an array mapping mapping each handle in $handle that can be found to that user's userid
- * @param $handles
+ * @param array $handles
  * @return array
  */
 function qa_db_user_get_handle_userids($handles)
 {
-	if (count($handles)) {
+	if (!empty($handles)) {
 		return qa_db_read_all_assoc(qa_db_query_sub(
 			'SELECT handle, userid FROM ^users WHERE handle IN ($)',
 			$handles
@@ -193,8 +193,8 @@ function qa_db_user_set($userid, $fields, $value = null)
 
 /**
  * Set the password of $userid to $password, and reset their salt at the same time
- * @param $userid
- * @param $password
+ * @param mixed $userid
+ * @param string $password
  * @return mixed
  */
 function qa_db_user_set_password($userid, $password)
@@ -221,9 +221,9 @@ function qa_db_user_set_password($userid, $password)
 
 /**
  * Switch on the $flag bit of the flags column for $userid if $set is true, or switch off otherwise
- * @param $userid
- * @param $flag
- * @param $set
+ * @param mixed $userid
+ * @param int $flag
+ * @param bool $set
  */
 function qa_db_user_set_flag($userid, $flag, $set)
 {
@@ -236,6 +236,7 @@ function qa_db_user_set_flag($userid, $flag, $set)
 
 /**
  * Return a random string to be used for a user's emailcode column
+ * @return string
  */
 function qa_db_user_rand_emailcode()
 {
@@ -249,6 +250,7 @@ function qa_db_user_rand_emailcode()
 
 /**
  * Return a random string to be used for a user's sessioncode column (for browser session cookies)
+ * @return string
  */
 function qa_db_user_rand_sessioncode()
 {
@@ -262,9 +264,9 @@ function qa_db_user_rand_sessioncode()
 
 /**
  * Set a row in the database user profile table to store $value for $field for $userid
- * @param $userid
- * @param $field
- * @param $value
+ * @param mixed $userid
+ * @param string $field
+ * @param string $value
  */
 function qa_db_user_profile_set($userid, $field, $value)
 {
@@ -278,8 +280,8 @@ function qa_db_user_profile_set($userid, $field, $value)
 
 /**
  * Note in the database that $userid just logged in from $ip address
- * @param $userid
- * @param $ip
+ * @param mixed $userid
+ * @param string $ip
  */
 function qa_db_user_logged_in($userid, $ip)
 {
@@ -292,8 +294,8 @@ function qa_db_user_logged_in($userid, $ip)
 
 /**
  * Note in the database that $userid just performed a write operation from $ip address
- * @param $userid
- * @param $ip
+ * @param mixed $userid
+ * @param string $ip
  */
 function qa_db_user_written($userid, $ip)
 {
@@ -306,9 +308,9 @@ function qa_db_user_written($userid, $ip)
 
 /**
  * Add an external login in the database for $source and $identifier for user $userid
- * @param $userid
- * @param $source
- * @param $identifier
+ * @param mixed $userid
+ * @param string $source
+ * @param string $identifier
  */
 function qa_db_user_login_add($userid, $source, $identifier)
 {
@@ -322,8 +324,8 @@ function qa_db_user_login_add($userid, $source, $identifier)
 
 /**
  * Return some information about the user with external login $source and $identifier in the database, if a match is found
- * @param $source
- * @param $identifier
+ * @param string $source
+ * @param string $identifier
  * @return array
  */
 function qa_db_user_login_find($source, $identifier)
@@ -338,7 +340,7 @@ function qa_db_user_login_find($source, $identifier)
 
 /**
  * Lock all tables if $sync is true, otherwise unlock them. Used to synchronize creation of external login mappings.
- * @param $sync
+ * @param bool $sync
  */
 function qa_db_user_login_sync($sync)
 {
@@ -360,8 +362,8 @@ function qa_db_user_login_sync($sync)
 /**
  * Reset the full set of context-specific (currently, per category) user levels for user $userid to $userlevels, where
  * $userlevels is an array of arrays, the inner arrays containing items 'entitytype', 'entityid' and 'level'.
- * @param $userid
- * @param $userlevels
+ * @param mixed $userid
+ * @param array $userlevels
  */
 function qa_db_user_levels_set($userid, $userlevels)
 {
@@ -382,8 +384,8 @@ function qa_db_user_levels_set($userid, $userlevels)
 
 /**
  * Get the information required for sending a mailing to the next $count users with userids greater than $lastuserid
- * @param $lastuserid
- * @param $count
+ * @param mixed $lastuserid
+ * @param int $count
  * @return array
  */
 function qa_db_users_get_mailing_next($lastuserid, $count)

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)

qa-include/pages/question-submit.php

@@ -33,11 +33,11 @@ require_once QA_INCLUDE_DIR . 'app/post-update.php';
  * Checks for a POSTed click on $question by the current user and returns true if it was permitted and processed. Pass
  * in the question's $answers, all $commentsfollows from it or its answers, and its closing $closepost (or null if
  * none). If there is an error to display, it will be passed out in $error.
- * @param $question
- * @param $answers
- * @param $commentsfollows
- * @param $closepost
- * @param $error
+ * @param array $question
+ * @param array $answers
+ * @param array $commentsfollows
+ * @param array $closepost
+ * @param string $error
  * @return bool
  */
 function qa_page_q_single_click_q($question, $answers, $commentsfollows, $closepost, &$error)
@@ -127,12 +127,12 @@ function qa_page_q_single_click_q($question, $answers, $commentsfollows, $closep
  * the $question, all of its $answers, and all $commentsfollows from it or its answers. Set $allowselectmove to whether
  * it is legitimate to change the selected answer for the question from one to another (this can't be done via Ajax).
  * If there is an error to display, it will be passed out in $error.
- * @param $answer
- * @param $question
- * @param $answers
- * @param $commentsfollows
- * @param $allowselectmove
- * @param $error
+ * @param array $answer
+ * @param array $question
+ * @param array $answers
+ * @param array $commentsfollows
+ * @param bool $allowselectmove
+ * @param string $error
  * @return bool
  */
 function qa_page_q_single_click_a($answer, $question, $answers, $commentsfollows, $allowselectmove, &$error)
@@ -231,10 +231,10 @@ function qa_page_q_single_click_a($answer, $question, $answers, $commentsfollows
  * Checks for a POSTed click on $comment by the current user and returns true if it was permitted and processed. Pass
  * in the antecedent $question and the comment's $parent post. If there is an error to display, it will be passed out
  * in $error.
- * @param $comment
- * @param $question
- * @param $parent
- * @param $error
+ * @param array $comment
+ * @param array $question
+ * @param array $parent
+ * @param string $error
  * @return bool
  */
 function qa_page_q_single_click_c($comment, $question, $parent, &$error)
@@ -322,8 +322,8 @@ function qa_page_q_single_click_c($comment, $question, $parent, &$error)
 /**
  * Check the form security (anti-CSRF protection) for one of the buttons shown for post $post. Return true if the
  * security passed, otherwise return false and set an error message in $error
- * @param $post
- * @param $error
+ * @param array $post
+ * @param string $error
  * @return bool
  */
 function qa_page_q_click_check_form_code($post, &$error)
@@ -341,12 +341,12 @@ function qa_page_q_click_check_form_code($post, &$error)
  * Processes a POSTed form to add an answer to $question, returning the postid if successful, otherwise null. Pass in
  * other $answers to the question and whether a $usecaptcha is required. The form fields submitted will be passed out
  * as an array in $in, as well as any $errors on those fields.
- * @param $question
- * @param $answers
- * @param $usecaptcha
- * @param $in
- * @param $errors
- * @return mixed|null
+ * @param array $question
+ * @param array $answers
+ * @param bool $usecaptcha
+ * @param array $in
+ * @param array $errors
+ * @return int|null
  */
 function qa_page_q_add_a_submit($question, $answers, $usecaptcha, &$in, &$errors)
 {
@@ -424,13 +424,13 @@ function qa_page_q_add_a_submit($question, $answers, $usecaptcha, &$in, &$errors
  * $question and the comment's $parent post. Set $usecaptcha to whether a captcha is required. Pass an array which
  * includes the other comments with the same parent in $commentsfollows (it can contain other posts which are ignored).
  * The form fields submitted will be passed out as an array in $in, as well as any $errors on those fields.
- * @param $question
- * @param $parent
- * @param $commentsfollows
- * @param $usecaptcha
- * @param $in
- * @param $errors
- * @return mixed|null
+ * @param array $question
+ * @param array $parent
+ * @param array $commentsfollows
+ * @param bool $usecaptcha
+ * @param array $in
+ * @param array $errors
+ * @return int|null
  */
 function qa_page_q_add_c_submit($question, $parent, $commentsfollows, $usecaptcha, &$in, &$errors)
 {
@@ -494,7 +494,7 @@ function qa_page_q_add_c_submit($question, $parent, $commentsfollows, $usecaptch
 
 /**
  * Return the array of information to be passed to filter modules for the post in $post (from the database)
- * @param $post
+ * @param array $post
  * @return array
  */
 function qa_page_q_prepare_post_for_filters($post)

qa-include/pages/question-view.php

@@ -27,8 +27,8 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Given a $question and its $childposts from the database, return a list of that question's answers
- * @param $question
- * @param $childposts
+ * @param array $question
+ * @param array $childposts
  * @return array
  */
 function qa_page_q_load_as($question, $childposts)
@@ -53,9 +53,9 @@ function qa_page_q_load_as($question, $childposts)
  * Given a $question, its $childposts and its answers $achildposts from the database,
  * return a list of comments or follow-on questions for that question or its answers.
  * Follow-on and duplicate questions are now returned, with their visibility determined in qa_page_q_comment_follow_list()
- * @param $question
- * @param $childposts
- * @param $achildposts
+ * @param array $question
+ * @param array $childposts
+ * @param array $achildposts
  * @param array $duplicateposts
  * @return array
  */
@@ -93,11 +93,10 @@ function qa_page_q_load_c_follows($question, $childposts, $achildposts, $duplica
  * Calculates which operations the current user may perform on a post. This function is a key part of Q2A's logic
  * and is ripe for overriding by plugins. The latter two arrays can contain additional posts retrieved from the
  * database, and these will be ignored.
- *
  * @param array $post The question/answer/comment to check.
- * @param array $parentpost The post's parent if there is one.
- * @param array $siblingposts The post's siblings (i.e. those with the same type and parent as the post).
- * @param array $childposts The post's children (e.g. comments on answers).
+ * @param array|null $parentpost The post's parent if there is one.
+ * @param array|null $siblingposts The post's siblings (i.e. those with the same type and parent as the post).
+ * @param array|null $childposts The post's children (e.g. comments on answers).
  * @return array List of elements that can be added to the post.
  */
 function qa_page_q_post_rules($post, $parentpost = null, $siblingposts = null, $childposts = null)
@@ -257,11 +256,11 @@ function qa_page_q_post_rules($post, $parentpost = null, $siblingposts = null, $
  * is closed, pass the post used to close this question in $closepost, otherwise null. $usershtml should be an array
  * which maps userids to HTML user representations, including the question's author and (if present) last editor. If a
  * form has been explicitly requested for the page, set $formrequested to true - this will hide the buttons.
- * @param $question
- * @param $parentquestion
- * @param $closepost
- * @param $usershtml
- * @param $formrequested
+ * @param array $question
+ * @param array|null $parentquestion
+ * @param int|null $closepost
+ * @param array $usershtml
+ * @param bool $formrequested
  * @return array
  */
 function qa_page_q_question_view($question, $parentquestion, $closepost, $usershtml, $formrequested)
@@ -492,11 +491,11 @@ function qa_page_q_question_view($question, $parentquestion, $closepost, $usersh
  * answer's $question and whether it $isselected. $usershtml should be an array which maps userids to HTML user
  * representations, including the answer's author and (if present) last editor. If a form has been explicitly requested
  * for the page, set $formrequested to true - this will hide the buttons.
- * @param $question
- * @param $answer
- * @param $isselected
- * @param $usershtml
- * @param $formrequested
+ * @param array $question
+ * @param array $answer
+ * @param bool $isselected
+ * @param array $usershtml
+ * @param bool $formrequested
  * @return array
  */
 function qa_page_q_answer_view($question, $answer, $isselected, $usershtml, $formrequested)
@@ -643,18 +642,17 @@ function qa_page_q_answer_view($question, $answer, $isselected, $usershtml, $for
  * current user. Pass the comment's $parent post and antecedent $question. $usershtml should be an array which maps
  * userids to HTML user representations, including the comments's author and (if present) last editor. If a form has
  * been explicitly requested for the page, set $formrequested to true - this will hide the buttons.
- * @param $question
- * @param $parent
- * @param $comment
- * @param $usershtml
- * @param $formrequested
+ * @param array $question
+ * @param array $parent
+ * @param array $comment
+ * @param array $usershtml
+ * @param bool $formrequested
  * @return array
  */
 function qa_page_q_comment_view($question, $parent, $comment, $usershtml, $formrequested)
 {
 	$commentid = $comment['postid'];
 	$questionid = ($parent['basetype'] == 'Q') ? $parent['postid'] : $parent['parentid'];
-	$answerid = ($parent['basetype'] == 'Q') ? null : $parent['postid'];
 	$userid = qa_get_logged_in_userid();
 	$cookieid = qa_cookie_get();
 
@@ -784,13 +782,13 @@ function qa_page_q_comment_view($question, $parent, $comment, $usershtml, $formr
  * comments' and follow on questions' authors and (if present) last editors. If a form has been explicitly requested
  * for the page, set $formrequested to true and pass the postid of the post for the form in $formpostid - this will
  * hide the buttons and remove the $formpostid comment from the list.
- * @param $question
- * @param $parent
- * @param $commentsfollows
- * @param $alwaysfull
- * @param $usershtml
- * @param $formrequested
- * @param $formpostid
+ * @param array $question
+ * @param array $parent
+ * @param array $commentsfollows
+ * @param bool $alwaysfull
+ * @param array $usershtml
+ * @param bool $formrequested
+ * @param int $formpostid
  * @return array
  */
 function qa_page_q_comment_follow_list($question, $parent, $commentsfollows, $alwaysfull, $usershtml, $formrequested, $formpostid)
@@ -865,7 +863,7 @@ function qa_page_q_comment_follow_list($question, $parent, $commentsfollows, $al
 		}
 	}
 
-	if (!count($commentlist['cs']))
+	if (empty($commentlist['cs']))
 		$commentlist['hidden'] = true;
 
 	return $commentlist;
@@ -877,14 +875,14 @@ function qa_page_q_comment_follow_list($question, $parent, $commentsfollows, $al
  * and the result of qa_user_captcha_reason() in $captchareason. Pass previous inputs from a submitted version of this
  * form in the array $in and resulting errors in $errors. If $loadnow is true, the form will be loaded immediately. Set
  * $formrequested to true if the user explicitly requested it, as opposed being shown automatically.
- * @param $qa_content
- * @param $formid
- * @param $captchareason
- * @param $question
- * @param $in
- * @param $errors
- * @param $loadnow
- * @param $formrequested
+ * @param array $qa_content
+ * @param string $formid
+ * @param string $captchareason
+ * @param array $question
+ * @param array $in
+ * @param array $errors
+ * @param bool $loadnow
+ * @param bool $formrequested
  * @return array
  */
 function qa_page_q_add_a_form(&$qa_content, $formid, $captchareason, $question, $in, $errors, $loadnow, $formrequested)
@@ -1026,14 +1024,14 @@ function qa_page_q_add_a_form(&$qa_content, $formid, $captchareason, $question,
  * to use for the form in $formid and the result of qa_user_captcha_reason() in $captchareason. Pass previous inputs
  * from a submitted version of this form in the array $in and resulting errors in $errors. If $loadfocusnow is true,
  * the form will be loaded and focused immediately.
- * @param $qa_content
- * @param $question
- * @param $parent
- * @param $formid
- * @param $captchareason
- * @param $in
- * @param $errors
- * @param $loadfocusnow
+ * @param array $qa_content
+ * @param array $question
+ * @param array $parent
+ * @param string $formid
+ * @param string $captchareason
+ * @param array $in
+ * @param array $errors
+ * @param bool $loadfocusnow
  * @return array
  */
 function qa_page_q_add_c_form(&$qa_content, $question, $parent, $formid, $captchareason, $in, $errors, $loadfocusnow)

qa-include/qa-db.php

@@ -19,6 +19,8 @@
 	More about this license: http://www.question2answer.org/license.php
 */
 
+use Q2A\Database\DbResult;
+
 if (!defined('QA_VERSION')) { // don't allow this page to be requested directly from browser
 	header('Location: ../');
 	exit;
@@ -42,8 +44,8 @@ function qa_db_allow_connect()
  * Connect to the Q2A database, select the right database, optionally install the $failhandler (and call it if necessary).
  * Uses mysqli as of Q2A 1.7.
  * @deprecated 1.9.0 Use DbConnection->connect() instead.
- * @param null $failhandler
- * @return mixed|void
+ * @param string|null $failhandler
+ * @return mixed
  */
 function qa_db_connect($failhandler = null)
 {
@@ -56,7 +58,7 @@ function qa_db_connect($failhandler = null)
 /**
  * If a DB error occurs, call the installed fail handler (if any) otherwise report error and exit immediately.
  * @deprecated 1.9.0 Use DbConnection->failError() instead.
- * @param $type
+ * @param string $type
  * @param int $errno
  * @param string $error
  * @param string $query
@@ -105,8 +107,8 @@ function qa_db_disconnect()
  * Run the raw $query, call the global failure handler if necessary, otherwise return the result resource.
  * If appropriate, also track the resources used by database queries, and the queries themselves, for performance debugging.
  * @deprecated 1.9.0 Use DbConnection->query() instead.
- * @param $query
- * @return mixed
+ * @param string $query
+ * @return DbResult
  */
 function qa_db_query_raw($query)
 {
@@ -119,8 +121,8 @@ function qa_db_query_raw($query)
 /**
  * Lower-level function to execute a query, which automatically retries if there is a MySQL deadlock error.
  * @deprecated 1.9.0 Use DbConnection->query() instead.
- * @param $query
- * @return mixed
+ * @param string $query
+ * @return DbResult
  */
 function qa_db_query_execute($query)
 {
@@ -133,8 +135,8 @@ function qa_db_query_execute($query)
 /**
  * Return $string escaped for use in queries to the Q2A database (to which a connection must have been made).
  * @deprecated 1.9.0 No longer needed: parameters passed to DbConnection->query() are automatically escaped.
- * @param $string
- * @return mixed
+ * @param string $string
+ * @return string
  */
 function qa_db_escape_string($string)
 {
@@ -151,8 +153,8 @@ function qa_db_escape_string($string)
  * Return $argument escaped for MySQL. Add quotes around it if $alwaysquote is true or it's not numeric.
  * If $argument is an array, return a comma-separated list of escaped elements, with or without $arraybrackets.
  * @deprecated 1.9.0
- * @param $argument
- * @param $alwaysquote
+ * @param mixed|null $argument
+ * @param bool $alwaysquote
  * @param bool $arraybrackets
  * @return mixed|string
  */
@@ -184,7 +186,7 @@ function qa_db_argument_to_mysql($argument, $alwaysquote, $arraybrackets = false
 /**
  * Return the full name (with prefix) of database table $rawname, usually if it used after a ^ symbol.
  * @deprecated 1.9.0 Use DbConnection->addTablePrefix() instead.
- * @param $rawname
+ * @param string $rawname
  * @return string
  */
 function qa_db_add_table_prefix($rawname)
@@ -198,7 +200,7 @@ function qa_db_add_table_prefix($rawname)
 /**
  * Callback function to add table prefixes, as used in qa_db_apply_sub().
  * @deprecated 1.9.0 No longer needed.
- * @param $matches
+ * @param array $matches
  * @return string
  */
 function qa_db_prefix_callback($matches)
@@ -214,8 +216,8 @@ function qa_db_prefix_callback($matches)
  * $ is replaced by the argument in quotes (even if it's a number), # only adds quotes if the argument is non-numeric.
  * It's important to use $ when matching a textual column since MySQL won't use indexes to compare text against numbers.
  * @deprecated 1.9.0 Use DbConnection->applyTableSub() instead.
- * @param $query
- * @param $arguments
+ * @param string $query
+ * @param array $arguments
  * @return mixed
  */
 function qa_db_apply_sub($query, $arguments)
@@ -258,7 +260,7 @@ function qa_db_apply_sub($query, $arguments)
  * Run $query after substituting ^, # and $ symbols, and return the result resource (or call fail handler).
  * @deprecated 1.9.0 Use DbConnection->query() instead.
  * @param string $query
- * @return mixed
+ * @return DbResult
  */
 function qa_db_query_sub($query) // arguments for substitution retrieved using func_get_args()
 {
@@ -266,13 +268,14 @@ function qa_db_query_sub($query) // arguments for substitution retrieved using f
 	return qa_service('database')->query($query, $params);
 }
 
+
 /**
  * Run $query after substituting ^, # and $ symbols, and return the result resource (or call fail handler).
  * Query parameters are passed as an array.
  * @deprecated 1.9.0 Use DbConnection->query() instead.
  * @param string $query
  * @param array $params
- * @return mixed
+ * @return DbResult
  */
 function qa_db_query_sub_params($query, $params)
 {
@@ -283,7 +286,7 @@ function qa_db_query_sub_params($query, $params)
 /**
  * Return the number of rows in $result. (Simple wrapper for mysqli_result::num_rows.)
  * @deprecated 1.9.0 Use DbResult->affectedRows() instead.
- * @param $result
+ * @param DbResult|mysqli_result $result
  * @return int
  */
 function qa_db_num_rows($result)
@@ -303,6 +306,7 @@ function qa_db_num_rows($result)
 /**
  * Return the value of the auto-increment column for the last inserted row.
  * @deprecated 1.9.0 Use DbConnection->lastInsertId() instead.
+ * @return string
  */
 function qa_db_last_insert_id()
 {
@@ -313,6 +317,7 @@ function qa_db_last_insert_id()
 /**
  * Return the number of rows affected by the last query.
  * @deprecated 1.9.0 Use DbResult->affectedRows() instead.
+ * @return int
  */
 function qa_db_affected_rows()
 {
@@ -324,16 +329,18 @@ function qa_db_affected_rows()
 /**
  * For the previous INSERT ... ON DUPLICATE KEY UPDATE query, return whether an insert operation took place.
  * @deprecated 1.9.0 Use DbResult->affectedRows() instead.
+ * @return bool
  */
 function qa_db_insert_on_duplicate_inserted()
 {
-	return (qa_db_affected_rows() == 1);
+	return false;
 }
 
 
 /**
  * Return a random integer (as a string) for use in a BIGINT column.
  * Actual limit is 18,446,744,073,709,551,615 - we aim for 18,446,743,999,999,999,999.
+ * @return string
  */
 function qa_db_random_bigint()
 {
@@ -344,6 +351,7 @@ function qa_db_random_bigint()
 /**
  * Return an array of the names of all tables in the Q2A database, converted to lower case.
  * No longer used by Q2A and shouldn't be needed.
+ * @return array
  */
 function qa_db_list_tables_lc()
 {
@@ -423,8 +431,8 @@ function qa_db_list_tables($onlyTablesWithPrefix = false)
 /**
  * Return the data specified by a single $selectspec - see long comment above.
  * @deprecated 1.9.0 Use DbConnection->singleSelect() instead.
- * @param $selectspec
- * @return array|mixed
+ * @param array $selectspec
+ * @return mixed
  */
 function qa_db_single_select($selectspec)
 {
@@ -496,9 +504,9 @@ function qa_db_post_select(&$outresult, $selectspec)
  * is from column $key if specified, otherwise it's integer. The value of each element in the returned array
  * is from column $value if specified, otherwise it's a named array of all columns, given an array of arrays.
  * @deprecated 1.9.0 Use DbResult->fetchAllAssoc() instead.
- * @param $result
- * @param string $key
- * @param mixed $value
+ * @param DbResult|mysqli_result $result
+ * @param string|null $key
+ * @param int|string|null $value
  * @return array
  */
 function qa_db_read_all_assoc($result, $key = null, $value = null)
@@ -529,7 +537,7 @@ function qa_db_read_all_assoc($result, $key = null, $value = null)
  * Return the first row from the $result resource as an array of [column name] => [column value].
  * If there's no first row, throw a fatal error unless $allowempty is true.
  * @deprecated 1.9.0 Use DbResult->fetchNextAssoc() instead.
- * @param $result
+ * @param DbResult|mysqli_result $result
  * @param bool $allowempty
  * @return array|null
  */
@@ -539,7 +547,6 @@ function qa_db_read_one_assoc($result, $allowempty = false)
 		return $allowempty ? $result->fetchNextAssoc() : $result->fetchNextAssocOrFail();
 	}
 
-
 	// backwards compatibility
 	if (!($result instanceof mysqli_result))
 		qa_fatal_error('Reading one assoc from invalid result');
@@ -559,7 +566,7 @@ function qa_db_read_one_assoc($result, $allowempty = false)
 /**
  * Return a numbered array containing the first (and presumably only) column from the $result resource.
  * @deprecated 1.9.0 Use DbResult->fetchAllValues() instead.
- * @param $result
+ * @param DbResult|mysqli_result $result
  * @return array
  */
 function qa_db_read_all_values($result)
@@ -568,7 +575,6 @@ function qa_db_read_all_values($result)
 		return $result->fetchAllValues(0);
 	}
 
-
 	// backwards compatibility
 	if (!($result instanceof mysqli_result))
 		qa_fatal_error('Reading column from invalid result');
@@ -586,9 +592,9 @@ function qa_db_read_all_values($result)
  * Return the first column of the first row (and presumably only cell) from the $result resource.
  * If there's no first row, throw a fatal error unless $allowempty is true.
  * @deprecated 1.9.0 Use DbResult->fetchOneValue() instead.
- * @param $result
+ * @param DbResult|mysqli_result $result
  * @param bool $allowempty
- * @return mixed|null
+ * @return string|null
  */
 function qa_db_read_one_value($result, $allowempty = false)
 {
@@ -596,7 +602,6 @@ function qa_db_read_one_value($result, $allowempty = false)
 		return $allowempty ? $result->fetchOneValue(0) : $result->fetchOneValueOrFail(0);
 	}
 
-
 	// backwards compatibility
 	if (!($result instanceof mysqli_result))
 		qa_fatal_error('Reading one value from invalid result');

qa-include/qa-feed.php

@@ -35,7 +35,7 @@ require_once QA_INCLUDE_DIR . 'app/options.php';
 
 /**
  * Database failure handler function for RSS feeds - outputs HTTP and text errors
- * @param $type
+ * @param string $type
  * @param int $errno
  * @param string $error
  * @param string $query
@@ -62,8 +62,8 @@ function qa_feed_not_found()
 /**
  * Common function to load appropriate set of questions for requested feed, check category exists, and set up page title
  * @param array $categoryslugs
- * @param string $allkey
- * @param string $catkey
+ * @param string|null $allkey
+ * @param string|null $catkey
  * @param string $title
  * @param array $questionselectspec1
  * @param array $questionselectspec2

qa-include/qa-install.php

@@ -34,7 +34,7 @@ qa_report_process_stage('init_install');
 if (!function_exists('qa_install_db_fail_handler')) {
 	/**
 	 * Handler function for database failures during the installation process
-	 * @param $type
+	 * @param string $type
 	 * @param int $errno
 	 * @param string $error
 	 * @param string $query

qa-include/qa-theme-base.php

@@ -38,29 +38,60 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 class qa_html_theme_base
 {
+	/** @var string */
 	public $template;
+
+	/** @var array */
 	public $content;
+
+	/** @var string */
 	public $rooturl;
+
+	/** @var string */
 	public $request;
-	public $isRTL; // (boolean) whether text direction is Right-To-Left
 
-	protected $minifyHtml; // (boolean) whether to indent the HTML
+	/**
+	 * Whether text direction is Right-To-Left
+	 *
+	 * @var bool
+	 */
+	public $isRTL;
+
+	/**
+	 * Whether to indent the HTML
+	 *
+	 * @var bool
+	 */
+	protected $minifyHtml;
+
+	/** @var int */
 	protected $indent = 0;
+
+	/** @var int */
 	protected $lines = 0;
+
+	/** @var array */
 	protected $context = array();
 
-	// whether to use new block layout in rankings (true) or fall back to tables (false)
+	/**
+	 * Whether to use new block layout in rankings (true) or fall back to tables (false)
+	 * @var bool
+	 */
 	protected $ranking_block_layout = false;
-	// theme 'slug' to use as CSS class
+
+	/**
+	 * Theme 'slug' to use as CSS class
+	 * @var string
+	 */
 	protected $theme;
 
 
 	/**
 	 * Initialize the object and assign local variables.
-	 * @param $template
-	 * @param $content
-	 * @param $rooturl
-	 * @param $request
+	 * @param string $template
+	 * @param string $content
+	 * @param string $rooturl
+	 * @param string $request
 	 */
 	public function __construct($template, $content, $rooturl, $request)
 	{
@@ -75,10 +106,10 @@ class qa_html_theme_base
 	/**
 	 * @deprecated PHP4-style constructor deprecated from 1.7; please use proper `__construct`
 	 * function instead.
-	 * @param $template
-	 * @param $content
-	 * @param $rooturl
-	 * @param $request
+	 * @param string $template
+	 * @param string $content
+	 * @param string $rooturl
+	 * @param string $request
 	 */
 	public function qa_html_theme_base($template, $content, $rooturl, $request)
 	{
@@ -90,7 +121,7 @@ class qa_html_theme_base
 	 * Output each element in $elements on a separate line, with automatic HTML indenting.
 	 * This should be passed markup which uses the <tag/> form for unpaired tags, to help keep
 	 * track of indenting, although its actual output converts these to <tag> for W3C validation.
-	 * @param $elements
+	 * @param array $elements
 	 */
 	public function output_array($elements)
 	{
@@ -132,7 +163,7 @@ class qa_html_theme_base
 	/**
 	 * Output $html at the current indent level, but don't change indent level based on the markup within.
 	 * Useful for user-entered HTML which is unlikely to follow the rules we need to track indenting.
-	 * @param $html
+	 * @param string $html
 	 */
 	public function output_raw($html)
 	{
@@ -144,8 +175,8 @@ class qa_html_theme_base
 	/**
 	 * Output the three elements ['prefix'], ['data'] and ['suffix'] of $parts (if they're defined),
 	 * with appropriate CSS classes based on $class, using $outertag and $innertag in the markup.
-	 * @param $parts
-	 * @param $class
+	 * @param array $parts
+	 * @param string $class
 	 * @param string $outertag
 	 * @param string $innertag
 	 * @param string $extraclass
@@ -167,8 +198,8 @@ class qa_html_theme_base
 
 	/**
 	 * Set some context, which be accessed via $this->context for a function to know where it's being used on the page.
-	 * @param $key
-	 * @param $value
+	 * @param string $key
+	 * @param string $value
 	 */
 	public function set_context($key, $value)
 	{
@@ -178,7 +209,7 @@ class qa_html_theme_base
 
 	/**
 	 * Clear some context (used at the end of the appropriate loop).
-	 * @param $key
+	 * @param string $key
 	 */
 	public function clear_context($key)
 	{
@@ -189,8 +220,8 @@ class qa_html_theme_base
 	/**
 	 * Reorder the parts of the page according to the $parts array which contains part keys in their new order. Call this
 	 * before main_parts(). See the docs for qa_array_reorder() in util/sort.php for the other parameters.
-	 * @param $parts
-	 * @param string $beforekey
+	 * @param array $parts
+	 * @param string|null $beforekey
 	 * @param bool $reorderrelative
 	 */
 	public function reorder_parts($parts, $beforekey = null, $reorderrelative = true)
@@ -203,8 +234,8 @@ class qa_html_theme_base
 
 	/**
 	 * Output the widgets (as provided in $this->content['widgets']) for $region and $place.
-	 * @param $region
-	 * @param $place
+	 * @param string $region
+	 * @param string $place
 	 */
 	public function widgets($region, $place)
 	{
@@ -1017,8 +1048,8 @@ class qa_html_theme_base
 	/**
 	 * Reorder the fields of $form according to the $keys array which contains the field keys in their new order. Call
 	 * before any fields are output. See the docs for qa_array_reorder() in util/sort.php for the other parameters.
-	 * @param $form
-	 * @param $keys
+	 * @param array
+	 * @param array $keys
 	 * @param mixed $beforekey
 	 * @param bool $reorderrelative
 	 */
@@ -1205,8 +1236,8 @@ class qa_html_theme_base
 	/**
 	 * Reorder the buttons of $form according to the $keys array which contains the button keys in their new order. Call
 	 * before any buttons are output. See the docs for qa_array_reorder() in util/sort.php for the other parameters.
-	 * @param $form
-	 * @param $keys
+	 * @param array $form
+	 * @param array $keys
 	 * @param mixed $beforekey
 	 * @param bool $reorderrelative
 	 */
@@ -1477,7 +1508,7 @@ class qa_html_theme_base
 	 * removed in a future version. Themes can switch to the new layout by setting the member
 	 * variable $ranking_block_layout to false.
 	 * @param $ranking
-	 * @param $class
+	 * @param string $class
 	 */
 	public function ranking_table($ranking, $class)
 	{
@@ -1507,7 +1538,7 @@ class qa_html_theme_base
 	/**
 	 * @deprecated See ranking_table above.
 	 * @param $item
-	 * @param $class
+	 * @param string $class
 	 * @param $spacer
 	 */
 	public function ranking_table_item($item, $class, $spacer)
@@ -1535,7 +1566,7 @@ class qa_html_theme_base
 
 	/**
 	 * @deprecated See ranking_table above.
-	 * @param $class
+	 * @param string $class
 	 */
 	public function ranking_spacer($class)
 	{
@@ -1897,8 +1928,8 @@ class qa_html_theme_base
 
 	/**
 	 * @deprecated Deprecated from 1.7; please use avatar() instead.
-	 * @param $post
-	 * @param $class
+	 * @param array $post
+	 * @param string $class
 	 * @param string $prefix
 	 */
 	public function post_avatar($post, $class, $prefix = null)

qa-include/util/image.php

@@ -39,8 +39,8 @@ function qa_has_gd_image()
  * Check if the image in $imagefile will be too big for PHP/GD to process given memory usage and limits
  * Pass the width and height limit beyond which the image will require scaling in $size (if any)
  * Returns false if the image will fit fine, otherwise a safe estimate of the factor the image should be sized by
- * @param $imagefile
- * @param int $size
+ * @param string $imagefile
+ * @param int|null $size
  * @return bool|float
  */
 function qa_image_file_too_big($imagefile, $size = null)
@@ -82,12 +82,12 @@ function qa_image_file_too_big($imagefile, $size = null)
  * Given $imagedata containing JPEG/GIF/PNG data, constrain it proportionally to fit in $maxwidth x $maxheight.
  * Return the new image data (will always be a JPEG), and set the $width and $height variables.
  * If $maxheight is omitted or set to null, assume it to be the same as $maxwidth.
- * @param $imagedata
+ * @param string $imagedata
  * @param int $width
  * @param int $height
  * @param int $maxwidth
- * @param int $maxheight
- * @return null|string
+ * @param int|null $maxheight
+ * @return string|null
  */
 function qa_image_constrain_data($imagedata, &$width, &$height, $maxwidth, $maxheight = null)
 {
@@ -119,7 +119,7 @@ function qa_image_constrain_data($imagedata, &$width, &$height, $maxwidth, $maxh
  * @param int $width
  * @param int $height
  * @param int $maxwidth
- * @param int $maxheight
+ * @param int|null $maxheight
  * @return bool
  */
 function qa_image_constrain(&$width, &$height, $maxwidth, $maxheight = null)
@@ -141,9 +141,9 @@ function qa_image_constrain(&$width, &$height, $maxwidth, $maxheight = null)
 
 /**
  * Resize the GD $image to $width and $height, setting it to null if the resize failed
- * @param $image
- * @param $width
- * @param $height
+ * @param resource $image
+ * @param int $width
+ * @param int $height
  */
 function qa_gd_image_resize(&$image, $width, $height)
 {
@@ -181,6 +181,7 @@ function qa_gd_image_jpeg($image, $output = false)
 
 /**
  * Return an array of strings listing the image formats that are supported
+ * @return array
  */
 function qa_gd_image_formats()
 {

qa-include/util/sort.php

@@ -27,9 +27,9 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
 
 /**
  * Sort the $array of inner arrays by sub-element $by1 of each inner array, and optionally then by sub-element $by2
- * @param $array
- * @param $by1
- * @param null $by2
+ * @param array $array
+ * @param string $by1
+ * @param string|null $by2
  */
 function qa_sort_by(&$array, $by1, $by2 = null)
 {
@@ -44,8 +44,8 @@ function qa_sort_by(&$array, $by1, $by2 = null)
 
 /**
  * Function used in uasort to implement qa_sort_by()
- * @param $a
- * @param $b
+ * @param array $a
+ * @param array $b
  * @return int
  */
 function qa_sort_by_fn($a, $b)
@@ -73,8 +73,8 @@ function qa_sort_by_fn($a, $b)
 /**
  * General comparison function for two values, textual or numeric
  * @deprecated
- * @param $a
- * @param $b
+ * @param int|float|string $a
+ * @param int|float|string $b
  * @return int
  */
 function qa_sort_cmp($a, $b)
@@ -89,9 +89,9 @@ function qa_sort_cmp($a, $b)
 /**
  * Inserts $addelements into $array, preserving their keys, before $beforekey in that array.
  * If $beforekey cannot be found, the elements are appended at the end of the array.
- * @param $array
- * @param $beforekey
- * @param $addelements
+ * @param array $array
+ * @param string $beforekey
+ * @param array $addelements
  */
 function qa_array_insert(&$array, $beforekey, $addelements)
 {
@@ -130,9 +130,9 @@ define('QA_ARRAY_AT_END', 0.9); // place all the elements at the end of the arra
  * element by passing the key of that element in $beforekey (if $beforekey is not found, the elements are moved to the
  * end of the array). Any of the QA_ARRAY_* values defined above can also be passed in the $beforekey parameter.
  * If $reorderrelative is true, the relative ordering between the elements will also be set by the order in $keys.
- * @param $array
- * @param $keys
- * @param mixed $beforekey
+ * @param array $array
+ * @param array $keys
+ * @param mixed|null $beforekey
  * @param bool $reorderrelative
  */
 function qa_array_reorder(&$array, $keys, $beforekey = null, $reorderrelative = true)

qa-include/util/string.php

@@ -421,7 +421,7 @@ function qa_string_initialize()
  * Return the UTF-8 input string converted into an array of words, changed $tolowercase (or not).
  * Set $delimiters to true to keep the delimiters after each word and tweak what we used for word
  * splitting with $splitideographs and $splithyphens.
- * @param $string
+ * @param string $string
  * @param bool $tolowercase
  * @param bool $delimiters
  * @param bool $splitideographs
@@ -521,8 +521,8 @@ function qa_slugify($string, $asciiOnly = true, $maxLength = null)
 
 /**
  * Convert an array of tags into a string for storage in the database
- * @param $tags
- * @return mixed|string
+ * @param array $tags
+ * @return string
  */
 function qa_tags_to_tagstring($tags)
 {
@@ -534,7 +534,7 @@ function qa_tags_to_tagstring($tags)
 
 /**
  * Convert a tag string as stored in the database into an array of tags
- * @param $tagstring
+ * @param string $tagstring
  * @return array|mixed
  */
 function qa_tagstring_to_tags($tagstring)
@@ -548,7 +548,6 @@ function qa_tagstring_to_tags($tagstring)
 /**
  * Converts a string to a single line and removes words from it until it fits in the given length. Words are removed
  * from a position around two thirds of the string and are replaced by the given ellipsis string
- *
  * @param string $string Text that will be turned into a single line and cut, if necessary
  * @param int $length Maximum allowed length of the returned string. This value can be overriden by the length of the
  * ellipsis if it is higher than the maximum allowed length
@@ -596,7 +595,7 @@ function qa_shorten_string_line($string, $length, $ellipsis = ' ... ')
 
 /**
  * Removes 4-byte Unicode characters (e.g. emoji) from a string due to missing support in MySQL < 5.5.3.
- * @param  string $string
+ * @param string $string
  * @return string
  */
 function qa_remove_utf8mb4($string)
@@ -611,8 +610,8 @@ function qa_remove_utf8mb4($string)
 
 /**
  * Return an array of the words within $wordstring, each of which can contain asterisks
- * @param $wordstring
- * @return array|mixed
+ * @param string $wordstring
+ * @return array
  */
 function qa_block_words_explode($wordstring)
 {
@@ -624,7 +623,7 @@ function qa_block_words_explode($wordstring)
 
 /**
  * Return a regular expression fragment corresponding to the block words $wordstring
- * @param $wordsstring
+ * @param string $wordsstring
  * @return mixed|string
  */
 function qa_block_words_to_preg($wordsstring)
@@ -652,8 +651,8 @@ function qa_block_words_to_preg($wordsstring)
 
 /**
  * Return an array of matches of the regular expression fragment $wordspreg in $string, [offset] => [length]
- * @param $string
- * @param $wordspreg
+ * @param string $string
+ * @param string $wordspreg
  * @return array
  */
 function qa_block_words_match_all($string, $wordspreg)
@@ -693,7 +692,7 @@ function qa_block_words_match_all($string, $wordspreg)
  * @param string $string
  * @param string $wordspreg
  * @param string $character
- * @return mixed
+ * @return string
  */
 function qa_block_words_replace($string, $wordspreg, $character = '*')
 {
@@ -713,7 +712,7 @@ function qa_block_words_replace($string, $wordspreg, $character = '*')
 
 /**
  * Return a random alphanumeric string (base 36) of $length
- * @param $length
+ * @param int $length
  * @return string
  */
 function qa_random_alphanum($length)
@@ -729,8 +728,8 @@ function qa_random_alphanum($length)
 
 /**
  * Return true or false to indicate whether $email is a valid email (this is pretty flexible compared to most real emails out there)
- * @param $email
- * @return bool|mixed
+ * @param string $email
+ * @return bool
  */
 function qa_email_validate($email)
 {
@@ -742,8 +741,8 @@ function qa_email_validate($email)
 
 /**
  * Return the number of characters in $string, preferably using PHP's multibyte string functions
- * @param $string
- * @return int|mixed
+ * @param string $string
+ * @return int
  */
 function qa_strlen($string)
 {
@@ -755,8 +754,8 @@ function qa_strlen($string)
 
 /**
  * Return a lower case version of $string, preferably using PHP's multibyte string functions
- * @param $string
- * @return mixed|string
+ * @param string $string
+ * @return string
  */
 function qa_strtolower($string)
 {
@@ -768,10 +767,10 @@ function qa_strtolower($string)
 
 /**
  * Return $length characters from $string, starting from $start, preferably using PHP's multibyte string functions
- * @param $string
- * @param $start
+ * @param string $string
+ * @param int $start
  * @param int $length
- * @return mixed|string
+ * @return string
  */
 function qa_substr($string, $start, $length = 2147483647)
 {
@@ -783,6 +782,7 @@ function qa_substr($string, $start, $length = 2147483647)
 
 /**
  * Return whether this version of PHP has been compiled with multibyte string support
+ * @return bool
  */
 function qa_has_multibyte()
 {
@@ -792,8 +792,8 @@ function qa_has_multibyte()
 
 /**
  * Return true if at least one of the values in array $matches is a substring of $string. Otherwise, return false.
- * @param $string
- * @param $matches
+ * @param string $string
+ * @param array $matches
  * @return bool
  */
 function qa_string_matches_one($string, $matches)