Skip to content

Q
question2answer
Commit 5a31d21a by pupi1985
Options

PHPDoc update in app/emails, app/messages, app/posts and app/users-edit

parent 929a312b
Showing with 127 additions and 123 deletions
qa-include/app/emails.php
......@@ -24,6 +24,7 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
exit;
}
use Q2A\Exceptions\FatalErrorException;
use Q2A\Notifications\Email;
use Q2A\Notifications\Mailer;
use Q2A\Notifications\Status as NotifyStatus;
......@@ -44,21 +45,22 @@ function qa_suspend_notifications($suspend = true)
* Send email to person with $userid and/or $email and/or $handle (null/invalid values are ignored or retrieved from
* user database as appropriate). Email uses $subject and $body, after substituting each key in $subs with its
* corresponding value, plus applying some standard substitutions such as ^site_title, ^site_url, ^handle and ^email.
* @param $userid
* @param $email
* @param $handle
* @param $subject
* @param $body
* @param $subs
* @param bool $html
* @return bool
* If notifications are suspended, then a null value is returned.
* @param mixed $userid
* @param string $email
* @param string $handle
* @param string $subject
* @param string $body
* @param array $subs
* @param bool|false $html
* @return bool|null
*/
function qa_send_notification($userid, $email, $handle, $subject, $body, $subs, $html = false)
{
if (qa_to_override(__FUNCTION__)) { $args=func_get_args(); return qa_call_override(__FUNCTION__, $args); }
if (NotifyStatus::isSuspended()) {
return;
return null;
}
if ($userid) {
......@@ -74,8 +76,9 @@ function qa_send_notification($userid, $email, $handle, $subject, $body, $subs,
/**
* Send the email based on the $params array - the following keys are required (some can be empty): fromemail,
* fromname, toemail, toname, subject, body, html
* @param $params
* @param array $params
* @return bool
* @throws phpmailerException
*/
function qa_send_email($params)
{
......
qa-include/app/messages.php
......@@ -28,10 +28,10 @@ if (!defined('QA_VERSION')) { // don't allow this page to be requested directly
/**
* Returns an HTML string describing the reason why user $fromuserid cannot post on the wall of $touserid who has
* user flags $touserflags. If there is no such reason the function returns false.
* @param $fromuserid
* @param $touserid
* @param $touserflags
* @return bool|mixed|string
* @param mixed $fromuserid
* @param mixed $touserid
* @param int $touserflags
* @return bool|string
*/
function qa_wall_error_html($fromuserid, $touserid, $touserflags)
{
......@@ -78,13 +78,13 @@ function qa_wall_error_html($fromuserid, $touserid, $touserflags)
/**
* Adds a post to the wall of user $touserid with handle $tohandle, containing $content in $format (e.g. '' for text or 'html')
* The post is by user $userid with handle $handle, and $cookieid is the user's current cookie (used for reporting the event).
* @param $userid
* @param $handle
* @param $cookieid
* @param $touserid
* @param $tohandle
* @param $content
* @param $format
* @param mixed $userid
* @param string $handle
* @param string $cookieid
* @param mixed $touserid
* @param string $tohandle
* @param string $content
* @param string $format
* @return mixed
*/
function qa_wall_add_post($userid, $handle, $cookieid, $touserid, $tohandle, $content, $format)
......@@ -113,10 +113,10 @@ function qa_wall_add_post($userid, $handle, $cookieid, $touserid, $tohandle, $co
/**
* Deletes the wall post described in $message (as obtained via qa_db_recent_messages_selectspec()). The deletion was performed
* by user $userid with handle $handle, and $cookieid is the user's current cookie (all used for reporting the event).
* @param $userid
* @param $handle
* @param $cookieid
* @param $message
* @param mixed $userid
* @param string $handle
* @param string $cookieid
* @param array $message
*/
function qa_wall_delete_post($userid, $handle, $cookieid, $message)
{
......@@ -136,9 +136,9 @@ function qa_wall_delete_post($userid, $handle, $cookieid, $message)
* Return the list of messages in $usermessages (as obtained via qa_db_recent_messages_selectspec()) with additional
* fields indicating what actions can be performed on them by the current user. The messages were retrieved beginning
* at offset $start in the database. Currently only 'deleteable' is relevant.
* @param $usermessages
* @param $start
* @return mixed
* @param array $usermessages
* @param int $start
* @return array
*/
function qa_wall_posts_add_rules($usermessages, $start)
{
......@@ -166,7 +166,7 @@ function qa_wall_posts_add_rules($usermessages, $start)
/**
* Returns an element to add to $qa_content['message_list']['messages'] for $message (as obtained via
* qa_db_recent_messages_selectspec() and then qa_wall_posts_add_rules()).
* @param $message
* @param array $message
* @return array
*/
function qa_wall_post_view($message)
......@@ -197,8 +197,8 @@ function qa_wall_post_view($message)
/**
* Returns an element to add to $qa_content['message_list']['messages'] with a link to view all wall posts
* @param $handle
* @param $start
* @param string $handle
* @param int $start
* @return array
*/
function qa_wall_view_more_link($handle, $start)
......@@ -214,11 +214,11 @@ function qa_wall_view_more_link($handle, $start)
* Hides the private message described in $message (as obtained via qa_db_messages_inbox_selectspec() or qa_db_messages_outbox_selectspec()).
* If both sender and receiver have hidden the message, it gets deleted from the database.
* Note: currently no event is reported here, so $handle/$cookieid are unused.
* @param $userid
* @param $handle
* @param $cookieid
* @param $message
* @param $box
* @param mixed $userid
* @param string $handle
* @param string $cookieid
* @param array $message
* @param string $box
*/
function qa_pm_delete($userid, $handle, $cookieid, $message, $box)
{
......
qa-include/app/posts.php
......@@ -49,18 +49,18 @@ require_once QA_INCLUDE_DIR . 'util/string.php';
* post - either to $email if it is specified and valid, or to the current email address of $userid if $email is '@'.
* If you're creating a question, the $extravalue parameter will be set as the custom extra field, if not null. For all
* post types you can specify the $name of the post's author, which is relevant if the $userid is null.
* @param $type
* @param $parentid
* @param $title
* @param $content
* @param string $type
* @param int|null $parentid
* @param string $title
* @param string $content
* @param string $format
* @param $categoryid
* @param $tags
* @param $userid
* @param $notify
* @param $email
* @param $extravalue
* @param $name
* @param int|null $categoryid
* @param array|null $tags
* @param mixed|null $userid
* @param string|null $notify
* @param string|null $email
* @param string|null $extravalue
* @param string|null $name
* @return mixed
*/
function qa_post_create($type, $parentid, $title, $content, $format = '', $categoryid = null, $tags = null, $userid = null,
......@@ -105,16 +105,16 @@ function qa_post_create($type, $parentid, $title, $content, $format = '', $categ
* Change the data stored for post $postid based on any of the $title, $content, $format, $tags, $notify, $email,
* $extravalue and $name parameters passed which are not null. The meaning of these parameters is the same as for
* qa_post_create() above. Pass the identify of the user making this change in $byuserid (or null for silent).
* @param $postid
* @param $title
* @param $content
* @param $format
* @param $tags
* @param $notify
* @param $email
* @param $byuserid
* @param $extravalue
* @param $name
* @param int $postid
* @param string|null $title
* @param string|null $content
* @param string $format
* @param array|null $tags
* @param string|null $notify
* @param string|null $email
* @param mixed|null $byuserid
* @param string|null $extravalue
* @param string $name
*/
function qa_post_set_content($postid, $title, $content, $format = null, $tags = null, $notify = null, $email = null, $byuserid = null, $extravalue = null, $name = null)
{
......@@ -166,9 +166,9 @@ function qa_post_set_content($postid, $title, $content, $format = null, $tags =
* Change the category of $postid to $categoryid. The category of all related posts (shown together on the same
* question page) will also be changed. Pass the identify of the user making this change in $byuserid (or null for an
* anonymous change).
* @param $postid
* @param $categoryid
* @param $byuserid
* @param int $postid
* @param int $categoryid
* @param mixed|null $byuserid
*/
function qa_post_set_category($postid, $categoryid, $byuserid = null)
{
......@@ -189,9 +189,9 @@ function qa_post_set_category($postid, $categoryid, $byuserid = null)
/**
* Set the selected best answer of $questionid to $answerid (or to none if $answerid is null). Pass the identify of the
* user in $byuserid (or null for an anonymous change).
* @param $questionid
* @param $answerid
* @param $byuserid
* @param int $questionid
* @param int|null $answerid
* @param mixed|null $byuserid
*/
function qa_post_set_selchildid($questionid, $answerid, $byuserid = null)
{
......@@ -210,11 +210,11 @@ function qa_post_set_selchildid($questionid, $answerid, $byuserid = null)
* Close $questionid if $closed is true, otherwise reopen it. If $closed is true, pass either the $originalpostid of
* the question that it is a duplicate of, or a $note to explain why it's closed. Pass the identifier of the user in
* $byuserid (or null for an anonymous change).
* @param $questionid
* @param int $questionid
* @param bool $closed
* @param $originalpostid
* @param $note
* @param $byuserid
* @param int|null $originalpostid
* @param string|null $note
* @param mixed|null $byuserid
*/
function qa_post_set_closed($questionid, $closed = true, $originalpostid = null, $note = null, $byuserid = null)
{
......@@ -251,9 +251,9 @@ function qa_post_is_closed(array $question)
* Hide $postid if $hidden is true, otherwise show the post. Pass the identify of the user making this change in
* $byuserid (or null for a silent change).
* @deprecated Replaced by qa_post_set_status.
* @param $postid
* @param int $postid
* @param bool $hidden
* @param $byuserid
* @param mixed|null $byuserid
*/
function qa_post_set_hidden($postid, $hidden = true, $byuserid = null)
{
......@@ -264,9 +264,9 @@ function qa_post_set_hidden($postid, $hidden = true, $byuserid = null)
/**
* Change the status of $postid to $status, which should be one of the QA_POST_STATUS_* constants defined in
* /qa-include/app/post-update.php. Pass the identify of the user making this change in $byuserid (or null for a silent change).
* @param $postid
* @param $status
* @param $byuserid
* @param int $postid
* @param int $status
* @param mixed|null $byuserid
*/
function qa_post_set_status($postid, $status, $byuserid = null)
{
......@@ -298,8 +298,8 @@ function qa_post_set_status($postid, $status, $byuserid = null)
/**
* Set the created date of $postid to $created, which is a unix timestamp.
* @param $postid
* @param $created
* @param int $postid
* @param int $created
*/
function qa_post_set_created($postid, $created)
{
......@@ -321,7 +321,7 @@ function qa_post_set_created($postid, $created)
/**
* Delete $postid from the database, hiding it first if appropriate.
* @param $postid
* @param int $postid
*/
function qa_post_delete($postid)
{
......@@ -365,9 +365,9 @@ function qa_post_delete($postid)
/**
* Return the full information from the database for $postid in an array.
* @param $postid
* @param $requiredbasetypes
* @return array|mixed
* @param int $postid
* @param string|null $requiredbasetypes
* @return array
*/
function qa_post_get_full($postid, $requiredbasetypes = null)
{
......@@ -387,8 +387,8 @@ function qa_post_get_full($postid, $requiredbasetypes = null)
* Return the handle corresponding to $userid, unless it is null in which case return null.
*
* @deprecated Deprecated from 1.7; use `qa_userid_to_handle($userid)` instead.
* @param $userid
* @return mixed|null
* @param mixed $userid
* @return string|null
*/
function qa_post_userid_to_handle($userid)
{
......@@ -398,8 +398,8 @@ function qa_post_userid_to_handle($userid)
/**
* Return the textual rendition of $content in $format (used for indexing).
* @param $content
* @param $format
* @param string $content
* @param string $format
* @return string
*/
function qa_post_content_to_text($content, $format)
......@@ -415,8 +415,8 @@ function qa_post_content_to_text($content, $format)
/**
* Return tagstring to store in the database based on $tags as an array or a comma-separated string.
* @param $tags
* @return mixed|string
* @param array|string $tags
* @return string
*/
function qa_post_tags_to_tagstring($tags)
{
......@@ -429,7 +429,7 @@ function qa_post_tags_to_tagstring($tags)
/**
* Return the full database records for all answers to question $questionid
* @param $questionid
* @param int $questionid
* @return array
*/
function qa_post_get_question_answers($questionid)
......@@ -449,7 +449,7 @@ function qa_post_get_question_answers($questionid)
/**
* Return the full database records for all comments or follow-on questions for question $questionid or its answers
* @param $questionid
* @param int $questionid
* @return array
*/
function qa_post_get_question_commentsfollows($questionid)
......@@ -477,8 +477,8 @@ function qa_post_get_question_commentsfollows($questionid)
/**
* Return the full database record for the post which closed $questionid, if there is any
* @param $questionid
* @return array|mixed
* @param int $questionid
* @return array|null
*/
function qa_post_get_question_closepost($questionid)
{
......@@ -488,7 +488,7 @@ function qa_post_get_question_closepost($questionid)
/**
* Return the full database records for all comments or follow-on questions for answer $answerid
* @param $answerid
* @param int $answerid
* @return array
*/
function qa_post_get_answer_commentsfollows($answerid)
......@@ -508,8 +508,8 @@ function qa_post_get_answer_commentsfollows($answerid)
/**
* Return $parent if it's the database record for a question, otherwise return the database record for its parent
* @param $parent
* @return array|mixed
* @param array $parent
* @return array
*/
function qa_post_parent_to_question($parent)
{
......
qa-include/app/users-edit.php
......@@ -19,6 +19,8 @@
More about this license: http://www.question2answer.org/license.php
*/
use Q2A\Exceptions\FatalErrorException;
if (!defined('QA_VERSION')) { // don't allow this page to be requested directly from browser
header('Location: ../../');
exit;
......@@ -39,9 +41,9 @@ if (!defined('QA_NEW_PASSWORD_LEN')){
/**
* Return $errors fields for any invalid aspect of user-entered $handle (username) and $email. Works by calling through
* to all filter modules and also rejects existing values in database unless they belongs to $olduser (if set).
* @param $handle
* @param $email
* @param $olduser
* @param string $handle
* @param string $email
* @param array $olduser
* @return array
*/
function qa_handle_email_filter(&$handle, &$email, $olduser = null)
......@@ -93,7 +95,7 @@ function qa_handle_email_filter(&$handle, &$email, $olduser = null)
/**
* Make $handle valid and unique in the database - if $allowuserid is set, allow it to match that user only
* @param $handle
* @param string $handle
* @return string
*/
function qa_handle_make_valid($handle)
......@@ -139,8 +141,8 @@ function qa_handle_make_valid($handle)
/**
* Return an array with a single element (key 'password') if user-entered $password is valid, otherwise an empty array.
* Works by calling through to all filter modules.
* @param $password
* @param $olduser
* @param string $password
* @param array $olduser
* @return array
*/
function qa_password_validate($password, $olduser = null)
......@@ -171,9 +173,9 @@ function qa_password_validate($password, $olduser = null)
* Create a new user (application level) with $email, $password, $handle and $level.
* Set $confirmed to true if the email address has been confirmed elsewhere.
* Handles user points, notification and optional email confirmation.
* @param $email
* @param $password
* @param $handle
* @param string $email
* @param string|null $password
* @param string $handle
* @param int $level
* @param bool $confirmed
* @return mixed
......@@ -232,7 +234,7 @@ function qa_create_new_user($email, $password, $handle, $level = QA_USER_LEVEL_B
/**
* Delete $userid and all their votes and flags. Their posts will become anonymous.
* Handles recalculations of votes and flags for posts this user has affected.
* @param $userid
* @param mixed $userid
* @return mixed
*/
function qa_delete_user($userid)
......@@ -265,7 +267,7 @@ function qa_delete_user($userid)
/**
* Set a new email confirmation code for the user and send it out
* @param $userid
* @param mixed $userid
* @return mixed
*/
function qa_send_new_confirm($userid)
......@@ -292,10 +294,10 @@ function qa_send_new_confirm($userid)
/**
* Set a new email confirmation code for the user and return the corresponding link. If the email code is also sent then that value
* is used. Otherwise, a new email code is generated
* @param $userid
* @param $handle
* @param $emailcode
* @return mixed|string
* @param mixed $userid
* @param string $handle
* @param string $emailcode
* @return string
*/
function qa_get_new_confirm_url($userid, $handle, $emailcode = null)
{
......@@ -314,9 +316,9 @@ function qa_get_new_confirm_url($userid, $handle, $emailcode = null)
/**
* Complete the email confirmation process for the user
* @param $userid
* @param $email
* @param $handle
* @param mixed $userid
* @param string $email
* @param string $handle
* @return mixed
*/
function qa_complete_confirm($userid, $email, $handle)
......@@ -339,10 +341,10 @@ function qa_complete_confirm($userid, $email, $handle)
/**
* Set the user level of user $userid with $handle to $level (one of the QA_USER_LEVEL_* constraints in /qa-include/app/users.php)
* Pass the previous user level in $oldlevel. Reports the appropriate event, assumes change performed by the logged in user.
* @param $userid
* @param $handle
* @param $level
* @param $oldlevel
* @param mixed $userid
* @param string $handle
* @param int $level
* @param int $oldlevel
*/
function qa_set_user_level($userid, $handle, $level, $oldlevel)
{
......@@ -368,9 +370,9 @@ function qa_set_user_level($userid, $handle, $level, $oldlevel)
/**
* Set the status of user $userid with $handle to blocked if $blocked is true, otherwise to unblocked. Reports the appropriate
* event, assumes change performed by the logged in user.
* @param $userid
* @param $handle
* @param $blocked
* @param mixed $userid
* @param string $handle
* @param string $blocked
*/
function qa_set_user_blocked($userid, $handle, $blocked)
{
......@@ -388,7 +390,7 @@ function qa_set_user_blocked($userid, $handle, $blocked)
/**
* Start the 'I forgot my password' process for $userid, sending reset code
* @param $userid
* @param mixed $userid
* @return mixed
*/
function qa_start_reset_user($userid)
......@@ -415,9 +417,8 @@ function qa_start_reset_user($userid)
/**
* Successfully finish the 'I forgot my password' process for $userid, sending new password
*
* @deprecated This function has been replaced by qa_finish_reset_user since Q2A 1.8
* @param $userid
* @param mixed $userid
* @return mixed
*/
function qa_complete_reset_user($userid)
......@@ -454,7 +455,7 @@ function qa_complete_reset_user($userid)
* Successfully finish the 'I forgot my password' process for $userid, cleaning the emailcode field and logging in the user
* @param mixed $userId The userid identifiying the user who will have the password reset
* @param string $newPassword The new password for the user
* @return void
* @return mixed
*/
function qa_finish_reset_user($userId, $newPassword)
{
......@@ -501,9 +502,9 @@ function qa_logged_in_user_flush()
/**
* Set the avatar of $userid to the image in $imagedata, and remove $oldblobid from the database if not null
* @param $userid
* @param $imagedata
* @param $oldblobid
* @param mixed $userid
* @param string $imagedata
* @param string $oldblobid
* @return bool
*/
function qa_set_user_avatar($userid, $imagedata, $oldblobid = 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