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 141 additions and 112 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-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