PHPDoc update in app/favorites, app/limits, app/options and app/users

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

@@ -92,8 +92,8 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Return $field of the currently logged in user, or null if not available
-	 * @param $field
-	 * @return null
+	 * @param string $field
+	 * @return string|null
 	 */
 	function qa_get_logged_in_user_field($field)
 	{
@@ -131,10 +131,10 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Return HTML to display for the avatar of $userid, constrained to $size pixels, with optional $padding to that size
-	 * @param $userid
-	 * @param $size
+	 * @param mixed $userid
+	 * @param int|null $size
 	 * @param bool $padding
-	 * @return mixed|null|string
+	 * @return string|null
 	 */
 	function qa_get_external_avatar_html($userid, $size, $padding = false)
 	{
@@ -183,8 +183,8 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Returns a verification code used to ensure that a user session can't be generated by another PHP script running on the same server
-	 * @param $userid
-	 * @return mixed|string
+	 * @param int $userid
+	 * @return string
 	 */
 	function qa_session_verify_code($userid)
 	{
@@ -197,9 +197,9 @@ if (QA_FINAL_EXTERNAL_USERS) {
 	/**
 	 * Set cookie in browser for username $handle with $sessioncode (in database).
 	 * Pass true if user checked 'Remember me' (either now or previously, as learned from cookie).
-	 * @param $handle
-	 * @param $sessioncode
-	 * @param $remember
+	 * @param string $handle
+	 * @param string $sessioncode
+	 * @param bool $remember
 	 * @return mixed
 	 */
 	function qa_set_session_cookie($handle, $sessioncode, $remember)
@@ -224,8 +224,8 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Set the session variables to indicate that $userid is logged in from $source
-	 * @param $userid
-	 * @param $source
+	 * @param int $userid
+	 * @param string|null $source
 	 * @return mixed
 	 */
 	function qa_set_session_user($userid, $source)
@@ -259,10 +259,10 @@ if (QA_FINAL_EXTERNAL_USERS) {
 	/**
 	 * Call for successful log in by $userid and $handle or successful log out with $userid=null.
 	 * $remember states if 'Remember me' was checked in the login form.
-	 * @param $userid
+	 * @param int|null $userid
 	 * @param string $handle
 	 * @param bool $remember
-	 * @param $source
+	 * @param string|null $source
 	 * @return mixed
 	 */
 	function qa_set_logged_in_user($userid, $handle = '', $remember = false, $source = null)
@@ -316,9 +316,9 @@ if (QA_FINAL_EXTERNAL_USERS) {
 	/**
 	 * Call to log in a user based on an external identity provider $source with external $identifier
 	 * A new user is created based on $fields if it's a new combination of $source and $identifier
-	 * @param $source
-	 * @param $identifier
-	 * @param $fields
+	 * @param string $source
+	 * @param string $identifier
+	 * @param array $fields
 	 * @return mixed
 	 */
 	function qa_log_in_external_user($source, $identifier, $fields)
@@ -483,8 +483,8 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Return $field of the currently logged in user
-	 * @param $field
-	 * @return mixed|null
+	 * @param string $field
+	 * @return string|null
 	 */
 	function qa_get_logged_in_user_field($field)
 	{
@@ -533,7 +533,7 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 		require_once QA_INCLUDE_DIR . 'util/image.php';
 
-		if (strlen($blobId) == 0 || (isset($size) && (int)$size <= 0)) {
+		if (strlen($blobId) == 0 || (isset($size) && $size <= 0)) {
 			return null;
 		}
 
@@ -550,7 +550,6 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Get HTML to display a username, linked to their user page.
-	 *
 	 * @param string $handle  The username.
 	 * @param bool $microdata  Whether to include microdata.
 	 * @param bool $favorited  Show the user as favorited.
@@ -609,13 +608,12 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Return the avatar URL, either Gravatar or from a blob ID, constrained to $size pixels.
-	 *
 	 * @param int $flags The user's flags
 	 * @param string $email The user's email. Only needed to return the Gravatar link
 	 * @param string $blobId The blob ID. Only needed to return the locally stored avatar
-	 * @param int $size The size to constrain the final image
+	 * @param int|null $size The size to constrain the final image
 	 * @param bool $absolute Whether the link returned should be absolute or relative
-	 * @return null|string The URL to the user's avatar or null if none could be found (not even as a default site avatar)
+	 * @return string|null The URL to the user's avatar or null if none could be found (not even as a default site avatar)
 	 */
 	function qa_get_user_avatar_url($flags, $email, $blobId, $size = null, $absolute = false)
 	{
@@ -638,7 +636,6 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Return HTML to display for the user's avatar, constrained to $size pixels, with optional $padding to that size
-	 *
 	 * @param int $flags The user's flags
 	 * @param string $email The user's email. Only needed to return the Gravatar HTML
 	 * @param string $blobId The blob ID. Only needed to return the locally stored avatar HTML
@@ -680,7 +677,7 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Return email address for user $userid (if not using single sign-on integration)
-	 * @param $userid
+	 * @param int $userid
 	 * @return string
 	 */
 	function qa_get_user_email($userid)
@@ -693,8 +690,8 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Called after a database write $action performed by a user $userid
-	 * @param $userid
-	 * @param $action
+	 * @param int $userid
+	 * @param string $action
 	 * @return mixed
 	 */
 	function qa_user_report_action($userid, $action)
@@ -709,8 +706,8 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Return textual representation of the user $level
-	 * @param $level
-	 * @return mixed|string
+	 * @param int $level
+	 * @return string
 	 */
 	function qa_user_level_string($level)
 	{
@@ -737,8 +734,8 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 	/**
 	 * Return an array of links to login, register, email confirm and logout pages (if not using single sign-on integration)
-	 * @param $rooturl
-	 * @param $tourl
+	 * @param string $rooturl
+	 * @param string|null $tourl
 	 * @return array
 	 */
 	function qa_get_login_links($rooturl, $tourl)
@@ -756,6 +753,7 @@ if (QA_FINAL_EXTERNAL_USERS) {
 
 /**
  * Return whether someone is logged in at the moment
+ * @return bool
  */
 function qa_is_logged_in()
 {
@@ -766,6 +764,7 @@ function qa_is_logged_in()
 
 /**
  * Return displayable handle/username of currently logged in user, or null if none
+ * @return string
  */
 function qa_get_logged_in_handle()
 {
@@ -775,6 +774,7 @@ function qa_get_logged_in_handle()
 
 /**
  * Return email of currently logged in user, or null if none
+ * @return string
  */
 function qa_get_logged_in_email()
 {
@@ -784,6 +784,7 @@ function qa_get_logged_in_email()
 
 /**
  * Return level of currently logged in user, or null if none
+ * @return string
  */
 function qa_get_logged_in_level()
 {
@@ -793,6 +794,7 @@ function qa_get_logged_in_level()
 
 /**
  * Return flags (see QA_USER_FLAGS_*) of currently logged in user, or null if none
+ * @return string
  */
 function qa_get_logged_in_flags()
 {
@@ -805,6 +807,7 @@ function qa_get_logged_in_flags()
 
 /**
  * Return an array of all the specific (e.g. per category) level privileges for the logged in user, retrieving from the database if necessary
+ * @return array
  */
 function qa_get_logged_in_levels()
 {
@@ -816,7 +819,7 @@ function qa_get_logged_in_levels()
 
 /**
  * Return an array mapping each userid in $userids to that user's handle (public username), or to null if not found
- * @param $userids
+ * @param array $userids
  * @return array
  */
 function qa_userids_to_handles($userids)
@@ -839,7 +842,7 @@ function qa_userids_to_handles($userids)
 
 /**
  * Return an string mapping the received userid to that user's handle (public username), or to null if not found
- * @param $userid
+ * @param array $userid
  * @return mixed|null
  */
 function qa_userid_to_handle($userid)
@@ -853,7 +856,7 @@ function qa_userid_to_handle($userid)
  * Return an array mapping each handle in $handles the user's userid, or null if not found. If $exactonly is true then
  * $handles must have the correct case and accents. Otherwise, handles are case- and accent-insensitive, and the keys
  * of the returned array will match the $handles provided, not necessary those in the DB.
- * @param $handles
+ * @param array $handles
  * @param bool $exactonly
  * @return array
  */
@@ -890,7 +893,7 @@ function qa_handles_to_userids($handles, $exactonly = false)
 
 /**
  * Return the userid corresponding to $handle (not case- or accent-sensitive)
- * @param $handle
+ * @param string $handle
  * @return mixed|null
  */
 function qa_handle_to_userid($handle)
@@ -912,7 +915,7 @@ function qa_handle_to_userid($handle)
 
 /**
  * Return the level of the logged in user for a post with $categoryids (expressing the full hierarchy to the final category)
- * @param $categoryids
+ * @param array $categoryids
  * @return mixed|null
  */
 function qa_user_level_for_categories($categoryids)
@@ -943,8 +946,8 @@ function qa_user_level_for_categories($categoryids)
 
 /**
  * Return the level of the logged in user for $post, as retrieved from the database
- * @param $post
- * @return mixed|null
+ * @param array $post
+ * @return int|null
  */
 function qa_user_level_for_post($post)
 {
@@ -959,6 +962,7 @@ function qa_user_level_for_post($post)
 
 /**
  * Return the maximum possible level of the logged in user in any context (i.e. for any category)
+ * @return int
  */
 function qa_user_level_maximum()
 {
@@ -978,9 +982,9 @@ function qa_user_level_maximum()
 /**
  * Check whether the logged in user has permission to perform $permitoption on post $post (from the database)
  * Other parameters and the return value are as for qa_user_permit_error(...)
- * @param $permitoption
- * @param $post
- * @param $limitaction
+ * @param string $permitoption
+ * @param array $post
+ * @param string|null $limitaction
  * @param bool $checkblocks
  * @return bool|string
  */
@@ -993,8 +997,8 @@ function qa_user_post_permit_error($permitoption, $post, $limitaction = null, $c
 /**
  * Check whether the logged in user would have permittion to perform $permitoption in any context (i.e. for any category)
  * Other parameters and the return value are as for qa_user_permit_error(...)
- * @param $permitoption
- * @param $limitaction
+ * @param string $permitoption
+ * @param string|null $limitaction
  * @param bool $checkblocks
  * @return bool|string
  */
@@ -1006,14 +1010,12 @@ function qa_user_maximum_permit_error($permitoption, $limitaction = null, $check
 
 /**
  * Check whether the logged in user has permission to perform an action.
- *
- * @param string $permitoption The permission to check (if null, this simply checks whether the user is blocked).
- * @param string $limitaction Constant from /qa-include/app/limits.php to check against user or IP rate limits.
- * @param int $userlevel A QA_USER_LEVEL_* constant to consider the user at a different level to usual (e.g. if
+ * @param string|null $permitoption The permission to check (if null, this simply checks whether the user is blocked).
+ * @param string|null $limitaction Constant from /qa-include/app/limits.php to check against user or IP rate limits.
+ * @param int|null $userlevel A QA_USER_LEVEL_* constant to consider the user at a different level to usual (e.g. if
  *   they are performing this action in a category for which they have elevated privileges).
  * @param bool $checkblocks Whether to check the user's blocked status.
- * @param array $userfields Cache for logged in user, containing keys 'userid', 'level' (optional), 'flags'.
- *
+ * @param array|null $userfields Cache for logged in user, containing keys 'userid', 'level' (optional), 'flags'.
  * @return bool|string The permission error, or false if no error. Possible errors, in order of priority:
  *   'login' => the user should login or register
  *   'level' => a special privilege level (e.g. expert) or minimum number of points is required
@@ -1061,13 +1063,11 @@ function qa_user_permit_error($permitoption = null, $limitaction = null, $userle
 
 /**
  * Check whether user can perform $permitoption. Result as for qa_user_permit_error(...).
- *
- * @param string $permitoption Permission option name (from database) for action.
- * @param int $userid ID of user (null for no user).
- * @param int $userlevel Level to check against.
- * @param int $userflags Flags for this user.
- * @param int $userpoints User's points: if $userid is currently logged in, you can set $userpoints=null to retrieve them only if necessary.
- *
+ * @param string|null $permitoption Permission option name (from database) for action.
+ * @param int|null $userid ID of user (null for no user).
+ * @param int|null $userlevel Level to check against.
+ * @param int|null $userflags Flags for this user.
+ * @param int|null $userpoints User's points: if $userid is currently logged in, you can set $userpoints=null to retrieve them only if necessary.
  * @return string|bool Reason the user is not permitted, or false if the operation can go ahead.
  */
 function qa_permit_error($permitoption, $userid, $userlevel, $userflags, $userpoints = null)
@@ -1096,12 +1096,10 @@ function qa_permit_error($permitoption, $userid, $userlevel, $userflags, $userpo
 
 /**
  * Check whether user can reach the permission level. Result as for qa_user_permit_error(...).
- *
  * @param int $permit Permission constant.
- * @param int $userid ID of user (null for no user).
- * @param int $userlevel Level to check against.
- * @param int $userflags Flags for this user.
- *
+ * @param int|null $userid ID of user (null for no user).
+ * @param int|null $userlevel Level to check against.
+ * @param int|null $userflags Flags for this user.
  * @return string|bool Reason the user is not permitted, or false if the operation can go ahead
  */
 function qa_permit_value_error($permit, $userid, $userlevel, $userflags)
@@ -1154,8 +1152,8 @@ function qa_permit_value_error($permit, $userid, $userlevel, $userflags)
  * 'approve' => captcha required because the user has not been approved
  * 'confirm' => captcha required because the user has not confirmed their email address
  * false => captcha is not required
- * @param $userlevel
- * @return bool|mixed|string
+ * @param int|null $userlevel
+ * @return bool|string
  */
 function qa_user_captcha_reason($userlevel = null)
 {
@@ -1183,8 +1181,8 @@ function qa_user_captcha_reason($userlevel = null)
 /**
  * Return whether a captcha should be presented to the logged in user for writing posts. You can pass in a
  * QA_USER_LEVEL_* constant in $userlevel to consider the user at a different level to usual.
- * @param $userlevel
- * @return bool|mixed
+ * @param int|null $userlevel
+ * @return bool|string
  */
 function qa_user_use_captcha($userlevel = null)
 {
@@ -1205,7 +1203,7 @@ function qa_user_use_captcha($userlevel = null)
  * 'confirm' => moderation required because the user has not confirmed their email address
  * 'points' => moderation required because the user has insufficient points
  * false => moderation is not required
- * @param $userlevel
+ * @param int|null $userlevel
  * @return bool|string
  */
 function qa_user_moderation_reason($userlevel = null)
@@ -1238,7 +1236,7 @@ function qa_user_moderation_reason($userlevel = null)
 
 /**
  * Return the label to display for $userfield as retrieved from the database, using default if no name set
- * @param $userfield
+ * @param array $userfield
  * @return string
  */
 function qa_user_userfield_label($userfield)
@@ -1264,6 +1262,7 @@ function qa_user_userfield_label($userfield)
 
 /**
  * Set or extend the cookie in browser of non logged-in users which identifies them for the purposes of form security (anti-CSRF protection)
+ * @return mixed
  */
 function qa_set_form_security_key()
 {
@@ -1287,9 +1286,9 @@ function qa_set_form_security_key()
 /**
  * Return the form security (anti-CSRF protection) hash for an $action (any string), that can be performed within
  * QA_FORM_EXPIRY_SECS of $timestamp (in unix seconds) by the current user.
- * @param $action
- * @param $timestamp
- * @return mixed|string
+ * @param string $action
+ * @param int $timestamp
+ * @return string
  */
 function qa_calc_form_security_hash($action, $timestamp)
 {
@@ -1307,8 +1306,8 @@ function qa_calc_form_security_hash($action, $timestamp)
 /**
  * Return the full form security (anti-CSRF protection) code for an $action (any string) performed within
  * QA_FORM_EXPIRY_SECS of now by the current user.
- * @param $action
- * @return mixed|string
+ * @param string $action
+ * @return string
  */
 function qa_get_form_security_code($action)
 {
@@ -1325,8 +1324,8 @@ function qa_get_form_security_code($action)
 /**
  * Return whether $value matches the expected form security (anti-CSRF protection) code for $action (any string) and
  * that the code has not expired (if more than QA_FORM_EXPIRY_SECS have passed). Logs causes for suspicion.
- * @param $action
- * @param $value
+ * @param string $action
+ * @param string|null $value
  * @return bool
  */
 function qa_check_form_security_code($action, $value)