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

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)