Skip to content

Q
question2answer
Commit a4d750a5 by pupi1985
Options

PHPDoc update in pages/question-submit, pages/question-view, qa-base and qa-theme-base

parent ac7d7558
Showing with 296 additions and 253 deletions
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-base.php
......@@ -35,7 +35,7 @@ define('QA_BUILD_DATE', '2019-01-12');
* Classes are mapped to PHP files with the underscores converted to directory separators. The Q2A_Util_Debug class is in
* the file qa-include/Q2A/Util/Debug.php. A class named Q2A_Db_User_Messages would be in a file qa-include/Q2A/Db/User/Messages.php.
*
* @param $class
* @param string $class
*/
function qa_autoload($class)
{
......@@ -86,7 +86,7 @@ if (!isset($qa_autoconnect) || $qa_autoconnect !== false) {
* Converts the $version string (e.g. 1.6.2.2) to a floating point that can be used for greater/lesser comparisons
* (PHP's version_compare() function is not quite suitable for our needs)
* @deprecated 1.8.2 no longer used
* @param $version
* @param string $version
* @return float
*/
function qa_version_to_float($version)
......@@ -109,7 +109,7 @@ function qa_version_to_float($version)
/**
* Returns true if the current Q2A version is lower than $version
* @param $version
* @param string $version
* @return bool
*/
function qa_qa_version_below($version)
......@@ -120,7 +120,7 @@ function qa_qa_version_below($version)
/**
* Returns true if the current PHP version is lower than $version
* @param $version
* @param string $version
* @return bool
*/
function qa_php_version_below($version)
......@@ -350,7 +350,7 @@ function qa_initialize_modularity()
/**
* Set up output buffering. Use gzip compression if option set and it's not an admin page (since some of these contain lengthy processes).
* @param $request
* @param string $request
* @return bool whether buffering was used
*/
function qa_initialize_buffering($request = '')
......@@ -418,10 +418,10 @@ function qa_initialize_postdb_plugins()
/**
* Standard database failure handler function which bring up the install/repair/upgrade page
* @param $type
* @param int $errno
* @param string $error
* @param string $query
* @param string $type
* @param int|null $errno
* @param string|null $error
* @param string|null $query
* @return mixed
*/
function qa_page_db_fail_handler($type, $errno = null, $error = null, $query = null)
......@@ -445,9 +445,9 @@ function qa_page_db_fail_handler($type, $errno = null, $error = null, $query = n
* Name, Description, Min Q2A & Min PHP are not currently used by themes.
*
* @deprecated Deprecated from 1.7; Q2A_Util_Metadata class and metadata.json files should be used instead
* @param $contents
* @param $type
* @param bool $versiononly
* @param string $contents
* @param string $type
* @param bool|null $versiononly
* @return array
*/
function qa_addon_metadata($contents, $type, $versiononly = false)
......@@ -538,12 +538,12 @@ function qa_load_override_files()
/**
* Register a module of $type named $name, whose class named $class is defined in file $include (or null if no include necessary)
* If this module comes from a plugin, pass in the local plugin $directory and the $urltoroot relative url for that directory
* @param $type
* @param $include
* @param $class
* @param $name
* @param string $type
* @param string $include
* @param string $class
* @param string $name
* @param string $directory
* @param string $urltoroot
* @param string|null $urltoroot
*/
function qa_register_module($type, $include, $class, $name, $directory = QA_INCLUDE_DIR, $urltoroot = null)
{
......@@ -568,10 +568,10 @@ function qa_register_module($type, $include, $class, $name, $directory = QA_INCL
/**
* Register a layer named $name, defined in file $include. If this layer comes from a plugin (as all currently do),
* pass in the local plugin $directory and the $urltoroot relative url for that directory
* @param $include
* @param $name
* @param string $include
* @param string $name
* @param string $directory
* @param string $urltoroot
* @param string|null $urltoroot
*/
function qa_register_layer($include, $name, $directory = QA_INCLUDE_DIR, $urltoroot = null)
{
......@@ -595,9 +595,9 @@ function qa_register_layer($include, $name, $directory = QA_INCLUDE_DIR, $urltor
/**
* Register a file $include containing override functions. If this file comes from a plugin (as all currently do),
* pass in the local plugin $directory and the $urltoroot relative url for that directory
* @param $include
* @param string $include
* @param string $directory
* @param string $urltoroot
* @param string|null $urltoroot
*/
function qa_register_overrides($include, $directory = QA_INCLUDE_DIR, $urltoroot = null)
{
......@@ -615,8 +615,8 @@ function qa_register_overrides($include, $directory = QA_INCLUDE_DIR, $urltoroot
* Register a set of language phrases, which should be accessed by the prefix $name/ in the qa_lang_*() functions.
* Pass in the $pattern representing the PHP files that define these phrases, where * in the pattern is replaced with
* the language code (e.g. 'fr') and/or 'default'. These files should be formatted like Q2A's qa-lang-*.php files.
* @param $pattern
* @param $name
* @param string $pattern
* @param string $name
*/
function qa_register_phrases($pattern, $name)
{
......@@ -640,10 +640,10 @@ function qa_register_phrases($pattern, $name)
/**
* Register a plugin module of $type named $name, whose class named $class is defined in file $include (or null if no include necessary)
* This function relies on some global variable values and can only be called from a plugin's qa-plugin.php file
* @param $type
* @param $include
* @param $class
* @param $name
* @param string $type
* @param string $include
* @param string $class
* @param string $name
*/
function qa_register_plugin_module($type, $include, $class, $name)
{
......@@ -659,8 +659,8 @@ function qa_register_plugin_module($type, $include, $class, $name)
/**
* Register a plugin layer named $name, defined in file $include. Can only be called from a plugin's qa-plugin.php file
* @param $include
* @param $name
* @param string $include
* @param string $name
*/
function qa_register_plugin_layer($include, $name)
{
......@@ -676,7 +676,7 @@ function qa_register_plugin_layer($include, $name)
/**
* Register a plugin file $include containing override functions. Can only be called from a plugin's qa-plugin.php file
* @param $include
* @param string $include
*/
function qa_register_plugin_overrides($include)
{
......@@ -692,8 +692,8 @@ function qa_register_plugin_overrides($include)
/**
* Register a file name $pattern within a plugin directory containing language phrases accessed by the prefix $name
* @param $pattern
* @param $name
* @param string $pattern
* @param string $name
*/
function qa_register_plugin_phrases($pattern, $name)
{
......@@ -712,8 +712,8 @@ function qa_register_plugin_phrases($pattern, $name)
/**
* Calls eval() on the PHP code in $eval which came from the file $filename. It supplements PHP's regular error reporting by
* displaying/logging (as appropriate) the original source filename, if an error occurred when evaluating the code.
* @param $eval
* @param $filename
* @param string $eval
* @param string $filename
*/
function qa_eval_from_file($eval, $filename)
{
......@@ -747,8 +747,8 @@ function qa_eval_from_file($eval, $filename)
/**
* Call $function with the arguments in the $args array (doesn't work with call-by-reference functions)
* @param $function
* @param $args
* @param string $function
* @param array $args
* @return mixed
*/
function qa_call($function, $args)
......@@ -776,7 +776,6 @@ function qa_call($function, $args)
/**
* Determines whether a function is to be overridden by a plugin. But if the function is being called with
* the _base suffix, any override will be bypassed due to $qa_direct.
*
* @param string $function The function to override
* @return string|null The name of the overriding function (of the form `qa_functionname_override_1_in_filename`)
*/
......@@ -804,8 +803,8 @@ function qa_to_override($function)
/**
* Call the function which immediately overrides $function with the arguments in the $args array
* @param $function
* @param $args
* @param string $function
* @param array $args
* @return mixed
*/
function qa_call_override($function, $args)
......@@ -827,7 +826,7 @@ function qa_call_override($function, $args)
/**
* Exit PHP immediately after reporting a shutdown with $reason to any installed process modules
* @param string $reason
* @param string|null $reason
*/
function qa_exit($reason = null)
{
......@@ -840,7 +839,7 @@ function qa_exit($reason = null)
/**
* Display $message in the browser, write it to server error log, and then stop abruptly
* @param $message
* @param string $message
* @return mixed
*/
function qa_fatal_error($message)
......@@ -885,7 +884,7 @@ function qa_list_module_types()
/**
* Return a list of names of registered modules of $type
* @param $type
* @param string $type
* @return array
*/
function qa_list_modules($type)
......@@ -896,8 +895,8 @@ function qa_list_modules($type)
/**
* Return an array containing information about the module of $type named $name
* @param $type
* @param $name
* @param string $type
* @param string $name
* @return array
*/
function qa_get_module_info($type, $name)
......@@ -908,8 +907,8 @@ function qa_get_module_info($type, $name)
/**
* Return an instantiated class for module of $type named $name, whose functions can be called, or null if it doesn't exist
* @param $type
* @param $name
* @param string $type
* @param string $name
* @return mixed|null
*/
function qa_load_module($type, $name)
......@@ -942,7 +941,7 @@ function qa_load_module($type, $name)
/**
* Return an array of instantiated clases for modules which have defined $method
* (all modules are loaded but not included in the returned array)
* @param $method
* @param string $method
* @return array
*/
function qa_load_all_modules_with($method)
......@@ -966,8 +965,8 @@ function qa_load_all_modules_with($method)
/**
* Return an array of instantiated clases for modules of $type which have defined $method
* (other modules of that type are also loaded but not included in the returned array)
* @param $type
* @param $method
* @param string $type
* @param string $method
* @return array
*/
function qa_load_modules_with($type, $method)
......@@ -991,13 +990,13 @@ function qa_load_modules_with($type, $method)
/**
* Return HTML representation of $string, work well with blocks of text if $multiline is true
* @param $string
* @param string $string
* @param bool $multiline
* @return mixed|string
* @return string
*/
function qa_html($string, $multiline = false)
{
$html = htmlspecialchars((string)$string);
$html = htmlspecialchars($string);
if ($multiline) {
$html = preg_replace('/\r\n?/', "\n", $html);
......@@ -1014,10 +1013,10 @@ function qa_html($string, $multiline = false)
* Return $html after ensuring it is safe, i.e. removing Javascripts and the like - uses htmLawed library
* Links open in a new window if $linksnewwindow is true. Set $storage to true if sanitization is for
* storing in the database, rather than immediate display to user - some think this should be less strict.
* @param $html
* @param string $html
* @param bool $linksnewwindow
* @param bool $storage
* @return mixed|string
* @return string
*/
function qa_sanitize_html($html, $linksnewwindow = false, $storage = false)
{
......@@ -1044,7 +1043,7 @@ function qa_sanitize_html($html, $linksnewwindow = false, $storage = false)
/**
* htmLawed hook function used to process tags in qa_sanitize_html(...)
* @param $element
* @param string $element
* @param array $attributes
* @return string
*/
......@@ -1074,19 +1073,19 @@ function qa_sanitize_html_hook_tag($element, $attributes = null)
/**
* Return XML representation of $string, which is similar to HTML but ASCII control characters are also disallowed
* @param $string
* @param string $string
* @return string
*/
function qa_xml($string)
{
return htmlspecialchars(preg_replace('/[\x00-\x08\x0B\x0C\x0E-\x1F]/', '', (string)$string));
return htmlspecialchars(preg_replace('/[\x00-\x08\x0B\x0C\x0E-\x1F]/', '', $string));
}
/**
* Return JavaScript representation of $value, putting in quotes if non-numeric or if $forcequotes is true. In the
* case of boolean values they are returned as the appropriate true or false string
* @param $value
* @param mixed $value
* @param bool $forcequotes
* @return string
*/
......@@ -1113,9 +1112,9 @@ function qa_js($value, $forcequotes = false)
/**
* Inform Q2A that the current request is $request (slash-separated, independent of the url scheme chosen),
* that the relative path to the Q2A root apperas to be $relativeroot, and the url scheme appears to be $usedformat
* @param $request
* @param $relativeroot
* @param $usedformat
* @param string $request
* @param string $relativeroot
* @param int|null $usedformat
* @return mixed
*/
function qa_set_request($request, $relativeroot, $usedformat = null)
......@@ -1132,6 +1131,7 @@ function qa_set_request($request, $relativeroot, $usedformat = null)
/**
* Returns the current Q2A request (slash-separated, independent of the url scheme chosen)
* @return string
*/
function qa_request()
{
......@@ -1144,8 +1144,8 @@ function qa_request()
/**
* Returns the indexed $part (as separated by slashes) of the current Q2A request, or null if it doesn't exist
* @param $part
* @return
* @param int $part
* @return string
*/
function qa_request_part($part)
{
......@@ -1167,8 +1167,8 @@ function qa_request_parts($start = 0)
/**
* Return string for incoming GET/POST/COOKIE value, stripping slashes if appropriate
* @param $string
* @return mixed|string
* @param string $string
* @return string
*/
function qa_gpc_to_string($string)
{
......@@ -1180,8 +1180,8 @@ function qa_gpc_to_string($string)
/**
* Return string with slashes added, if appropriate for later removal by qa_gpc_to_string()
* @param $string
* @return mixed|string
* @param string $string
* @return string
*/
function qa_string_to_gpc($string)
{
......@@ -1193,8 +1193,8 @@ function qa_string_to_gpc($string)
/**
* Return string for incoming GET field, or null if it's not defined
* @param $field
* @return mixed|null|string
* @param string $field
* @return mixed|null
*/
function qa_get($field)
{
......@@ -1207,7 +1207,7 @@ function qa_get($field)
/**
* Return string for incoming POST field, or null if it's not defined.
* While we're at it, trim() surrounding white space and converted to Unix line endings.
* @param $field
* @param string $field
* @return mixed|null
*/
function qa_post_text($field)
......@@ -1220,8 +1220,8 @@ function qa_post_text($field)
/**
* Return an array for incoming POST field, or null if it's not an array or not defined.
* While we're at it, trim() surrounding white space for each value and convert them to Unix line endings.
* @param $field
* @return array|mixed|null
* @param string $field
* @return mixed|null
*/
function qa_post_array($field)
{
......@@ -1242,8 +1242,8 @@ function qa_post_array($field)
/**
* Return true if form button $name was clicked (as type=submit/image) to create this page request, or if a
* simulated click was sent for the button (via 'qa_click' POST field)
* @param $name
* @return bool|mixed
* @param string $name
* @return bool
*/
function qa_clicked($name)
{
......@@ -1255,7 +1255,7 @@ function qa_clicked($name)
/**
* Determine the remote IP address of the user accessing the site.
* @return mixed String representing IP if it's available, or null otherwise.
* @return string|null String representing IP if it's available, or null otherwise.
*/
function qa_remote_ip_address()
{
......@@ -1270,6 +1270,7 @@ function qa_remote_ip_address()
* is too big to be properly processed by PHP, usually because there is an attachment in the HTTP request. A warning
* is added to the server's log displaying the size of the file that triggered this situation. It is important to note
* that whenever this happens the $_POST and $_FILES superglobals are empty.
* @return bool
*/
function qa_post_limit_exceeded()
{
......@@ -1283,6 +1284,8 @@ function qa_post_limit_exceeded()
$postmaxsize = convert_to_bytes($unit, $postmaxsize);
return $_SERVER['CONTENT_LENGTH'] > $postmaxsize;
}
return false;
}
......@@ -1290,8 +1293,8 @@ function qa_post_limit_exceeded()
* Turns a numeric value and a unit (g/m/k) into bytes
* @param string $unit One of 'g', 'm', 'k'. It is case insensitive
* @param int $value The value to turn into bytes
* @return int The amount of bytes the unit and the value represent. If the unit is not one of 'g', 'm' or 'k' then
* the original value is returned
* @return int The amount of bytes the unit and the value represent. If the unit is not one of 'g', 'm' or 'k' then the
* original value is returned
*/
function convert_to_bytes($unit, $value)
{
......@@ -1311,7 +1314,7 @@ function convert_to_bytes($unit, $value)
/**
* Whether we are responding to an HTTP GET request
* Return true if we are responding to an HTTP GET request
* @return bool True if the request is GET
*/
function qa_is_http_get()
......@@ -1323,6 +1326,7 @@ function qa_is_http_get()
/**
* Return true if we are responding to an HTTP POST request
* @return bool True if the request is POST
*/
function qa_is_http_post()
{
......@@ -1334,6 +1338,7 @@ function qa_is_http_post()
/**
* Return true if we appear to be responding to a secure HTTP request (but hard to be sure)
* @return bool
*/
function qa_is_https_probably()
{
......@@ -1346,6 +1351,7 @@ function qa_is_https_probably()
/**
* Return true if it appears the page request is coming from a human using a web browser, rather than a search engine
* or other bot. Based on a whitelist of terms in user agents, this can easily be tricked by a scraper or bad bot.
* @return bool
*/
function qa_is_human_probably()
{
......@@ -1363,7 +1369,9 @@ function qa_is_human_probably()
/**
* Return true if it appears that the page request is coming from a mobile client rather than a desktop/laptop web browser
* Return true if it appears that the page request is coming from a mobile client rather than a desktop/laptop web
* browser
* @return bool
*/
function qa_is_mobile_probably()
{
......@@ -1405,7 +1413,7 @@ function qa_is_mobile_probably()
* loading an option now will cause a problem (see issue in qa_default_option()). The part of
* $identifier before the slash (/) replaces the * in the qa-lang-*.php file references, and the
* part after the / is the key of the array element to be taken from that file's returned result.
* @param $identifier
* @param string $identifier
* @return string
*/
function qa_lang($identifier)
......@@ -1455,8 +1463,8 @@ function qa_lang($identifier)
/**
* Return the translated string for $identifier, with $symbol substituted for $textparam
* @param $identifier
* @param $textparam
* @param string $identifier
* @param string $textparam
* @param string $symbol
* @return mixed
*/
......@@ -1468,8 +1476,8 @@ function qa_lang_sub($identifier, $textparam, $symbol = '^')
/**
* Return the translated string for $identifier, converted to HTML
* @param $identifier
* @return mixed|string
* @param string $identifier
* @return string
*/
function qa_lang_html($identifier)
{
......@@ -1479,8 +1487,8 @@ function qa_lang_html($identifier)
/**
* Return the translated string for $identifier converted to HTML, with $symbol *then* substituted for $htmlparam
* @param $identifier
* @param $htmlparam
* @param string $identifier
* @param string $htmlparam
* @param string $symbol
* @return mixed
*/
......@@ -1493,8 +1501,8 @@ function qa_lang_html_sub($identifier, $htmlparam, $symbol = '^')
/**
* Return an array containing the translated string for $identifier converted to HTML, then split into three,
* with $symbol substituted for $htmlparam in the 'data' element, and obvious 'prefix' and 'suffix' elements
* @param $identifier
* @param $htmlparam
* @param string $identifier
* @param string $htmlparam
* @param string $symbol
* @return array
*/
......@@ -1518,6 +1526,7 @@ function qa_lang_html_sub_split($identifier, $htmlparam, $symbol = '^')
/**
* Return the relative path to the Q2A root (if it was previously set by qa_set_request())
* @return string
*/
function qa_path_to_root()
{
......@@ -1530,6 +1539,7 @@ function qa_path_to_root()
/**
* Return an array of mappings of Q2A requests, as defined in the qa-config.php file
* @return array
*/
function qa_get_request_map()
{
......@@ -1545,11 +1555,11 @@ function qa_get_request_map()
* Slashes in $request will not be urlencoded, but any other characters will.
* If $neaturls is set, use that, otherwise retrieve the option. If $rooturl is set, take
* that as the root of the Q2A site, otherwise use path to root which was set elsewhere.
* @param $request
* @param array $params
* @param string $rooturl
* @param int $neaturls
* @param string $anchor
* @param string $request
* @param array|null $params
* @param string|null $rooturl
* @param int|null $neaturls
* @param string|null $anchor
* @return string
*/
function qa_path($request, $params = null, $rooturl = null, $neaturls = null, $anchor = null)
......@@ -1623,11 +1633,11 @@ function qa_path($request, $params = null, $rooturl = null, $neaturls = null, $a
/**
* Return HTML representation of relative URI path for $request - see qa_path() for other parameters
* @param $request
* @param array $params
* @param string $rooturl
* @param int $neaturls
* @param string $anchor
* @param string $request
* @param array|null $params
* @param string|null $rooturl
* @param int|null $neaturls
* @param string|null $anchor
* @return mixed|string
*/
function qa_path_html($request, $params = null, $rooturl = null, $neaturls = null, $anchor = null)
......@@ -1638,9 +1648,9 @@ function qa_path_html($request, $params = null, $rooturl = null, $neaturls = nul
/**
* Return the absolute URI for $request - see qa_path() for other parameters
* @param $request
* @param array $params
* @param string $anchor
* @param string $request
* @param array|null $params
* @param string|null $anchor
* @return string
*/
function qa_path_absolute($request, $params = null, $anchor = null)
......@@ -1672,9 +1682,9 @@ function qa_q_request($questionid, $title)
/**
* Return the HTML anchor that should be used for post $postid with $basetype (Q/A/C)
* @param $basetype
* @param $postid
* @return mixed|string
* @param string $basetype
* @param int $postid
* @return string
*/
function qa_anchor($basetype, $postid)
{
......@@ -1687,12 +1697,12 @@ function qa_anchor($basetype, $postid)
/**
* Return the URL for question $questionid with $title, possibly using $absolute URLs.
* To link to a specific answer or comment in a question, set $showtype and $showid accordingly.
* @param $questionid
* @param $title
* @param int $questionid
* @param string $title
* @param bool $absolute
* @param string $showtype
* @param int $showid
* @return mixed|string
* @param string|null $showtype
* @param int|null $showid
* @return string
*/
function qa_q_path($questionid, $title, $absolute = false, $showtype = null, $showid = null)
{
......@@ -1713,11 +1723,11 @@ function qa_q_path($questionid, $title, $absolute = false, $showtype = null, $sh
/**
* Return the HTML representation of the URL for $questionid - other parameters as for qa_q_path()
* @param $questionid
* @param $title
* @param bool $absolute
* @param string $showtype
* @param int $showid
* @param int $questionid
* @param string $title
* @param bool|null $absolute
* @param string|null $showtype
* @param int|null $showid
* @return mixed|string
*/
function qa_q_path_html($questionid, $title, $absolute = false, $showtype = null, $showid = null)
......@@ -1728,8 +1738,8 @@ function qa_q_path_html($questionid, $title, $absolute = false, $showtype = null
/**
* Return the request for the specified $feed
* @param $feed
* @return mixed|string
* @param string $feed
* @return string
*/
function qa_feed_request($feed)
{
......@@ -1741,6 +1751,7 @@ function qa_feed_request($feed)
/**
* Return an HTML-ready relative URL for the current page, preserving GET parameters - this is useful for action="..." in HTML forms
* @return string
*/
function qa_self_html()
{
......@@ -1755,12 +1766,12 @@ function qa_self_html()
/**
* Return HTML for hidden fields to insert into a <form method="get"...> on the page.
* This is needed because any parameters on the URL will be lost when the form is submitted.
* @param $request
* @param array $params
* @param string $rooturl
* @param int $neaturls
* @param string $anchor
* @return mixed|string
* @param string $request
* @param array|null $params
* @param string|null $rooturl
* @param int|null $neaturls
* @param string|null $anchor
* @return string
*/
function qa_path_form_html($request, $params = null, $rooturl = null, $neaturls = null, $anchor = null)
{
......@@ -1784,11 +1795,11 @@ function qa_path_form_html($request, $params = null, $rooturl = null, $neaturls
/**
* Redirect the user's web browser to $request and then we're done - see qa_path() for other parameters
* @param $request
* @param array $params
* @param string $rooturl
* @param int $neaturls
* @param string $anchor
* @param string $request
* @param array|null $params
* @param string|null $rooturl
* @param int|null $neaturls
* @param string|null $anchor
* @return mixed
*/
function qa_redirect($request, $params = null, $rooturl = null, $neaturls = null, $anchor = null)
......@@ -1801,7 +1812,7 @@ function qa_redirect($request, $params = null, $rooturl = null, $neaturls = null
/**
* Redirect the user's web browser to page $path which is already a URL
* @param $url
* @param string $url
* @return mixed
*/
function qa_redirect_raw($url)
......@@ -1817,8 +1828,8 @@ function qa_redirect_raw($url)
/**
* Return the contents of remote $url, using file_get_contents() if possible, otherwise curl functions
* @param $url
* @return mixed|string
* @param string $url
* @return bool|string
*/
function qa_retrieve_url($url)
{
......@@ -1875,9 +1886,9 @@ function qa_service($key, $object = null)
/**
* Shortcut to get or set an option value without specifying database
* @param $name
* @param mixed $value
* @return
* @param string $name
* @param mixed|null $value
* @return string
*/
function qa_opt($name, $value = null)
{
......@@ -1898,7 +1909,7 @@ function qa_opt($name, $value = null)
/**
* Simple method to output a preformatted variable
* @param $var
* @param mixed $var
*/
function qa_debug($var)
{
......@@ -1925,12 +1936,12 @@ function qa_suspend_event_reports($suspend = true)
/**
* Send a notification of event $event by $userid, $handle and $cookieid to all event modules, with extra $params
* @param $event
* @param $userid
* @param $handle
* @param $cookieid
* @param string $event
* @param mixed $userid
* @param string $handle
* @param string $cookieid
* @param array $params
* @return mixed|void
* @return mixed
*/
function qa_report_event($event, $userid, $handle, $cookieid, $params = array())
{
......@@ -1946,7 +1957,10 @@ function qa_report_event($event, $userid, $handle, $cookieid, $params = array())
$eventmodule->process_event($event, $userid, $handle, $cookieid, $params);
}
/**
* Execute the given $method in all process modules. Parameters can be sent as arguments.
* @param string $method
*/
function qa_report_process_stage($method) // can have extra params
{
global $qa_process_reports_suspended;
......
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)
......
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