Skip to content

Q
question2answer
Commit 53749f1e by pupi1985
Options

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

parent 5669d75e
Showing with 96 additions and 97 deletions
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)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment