Samwilson has uploaded a new change for review. (
https://gerrit.wikimedia.org/r/344301 )
Change subject: Fix various docblock formatting
......................................................................
Fix various docblock formatting
This fixes some errors in docblock formatting to bring things into
line with MediaWiki coding standards (not all of which are yet
caught by phpcs).
Change-Id: I06b7fc3a9fe09e412b3200b597ce01ef7e7d5ae3
---
M LoginNotify.hooks.php
M LoginNotify_body.php
2 files changed, 47 insertions(+), 32 deletions(-)
git pull ssh://gerrit.wikimedia.org:29418/mediawiki/extensions/LoginNotify
refs/changes/01/344301/1
diff --git a/LoginNotify.hooks.php b/LoginNotify.hooks.php
index f560f0e..7f4a304 100644
--- a/LoginNotify.hooks.php
+++ b/LoginNotify.hooks.php
@@ -16,9 +16,9 @@
/**
* Add LoginNotify events to Echo
*
- * @param $notifications array of Echo notifications
- * @param $notificationCategories array of Echo notification categories
- * @param $icons array of icon details
+ * @param string[] &$notifications Array of Echo notifications
+ * @param string[] &$notificationCategories Array of Echo notification
categories
+ * @param string[] &$icons Array of icon details
* @return bool
*/
public static function onBeforeCreateEchoEvent(
@@ -83,9 +83,9 @@
* Old hook for pre 1.27 or wikis with auth manager disabled.
*
* @todo Doesn't catcha captcha or throttle failures
- * @param $user User User in question
- * @param $pass String password
- * @param $retval int LoginForm constant (e.g. LoginForm::SUCCESS)
+ * @param User $user User in question.
+ * @param string $pass The password (parameter not used).
+ * @param integer $retval A LoginForm constant (e.g.
LoginForm::SUCCESS).
*/
public static function onLoginAuthenticateAudit( User $user, $pass,
$retval ) {
if ( $retval === LoginForm::WRONG_PASS ) {
@@ -98,9 +98,9 @@
/**
* Hook for login auditing post 1.27
*
- * @param $ret AuthenticationResponse Is login succesful?
- * @param $user User|null User object on successful auth
- * @param $username String Username for failed attempts.
+ * @param AuthenticationResponse $ret Is login successful?
+ * @param User|null $user User object on successful auth
+ * @param string $username Username for failed attempts.
*/
public static function onAuthManagerLoginAuthenticateAudit(
AuthenticationResponse $ret, $user, $username
@@ -123,6 +123,12 @@
// statuses.
}
+ /**
+ * Handle a successful login (clear the attempt counter, send a notice,
and record the
+ * current IP address as known).
+ *
+ * @param User $user The user who logged in.
+ */
public static function doSuccessfulLogin( User $user ) {
$loginNotify = new LoginNotify();
$loginNotify->clearCounters( $user );
@@ -130,6 +136,11 @@
$loginNotify->setCurrentAddressAsKnown( $user );
}
+ /**
+ * Handle a failed login (record the failure).
+ *
+ * @param User $user The user that failed to log in.
+ */
public static function doFailedLogin( User $user ) {
$loginNotify = new LoginNotify();
$loginNotify->recordFailure( $user );
@@ -140,8 +151,8 @@
*
* Set a cookie saying this is a known computer when creating an
account.
*
- * @todo This still sets cookies if user creates account well logged in
as someone else.
- * @param User $user
+ * @todo This still sets cookies if user creates an account while
logged in as someone else.
+ * @param User $user The user that has been created.
* @param boolean $byMail Account created by email
*/
public static function onAddNewAccount( User $user, $byMail ) {
@@ -173,8 +184,8 @@
* This is a bit hacky. Used to be able to set a different
* default for admins then other users
*
- * @param $user User
- * @param &$options array
+ * @param User $user The user in question.
+ * @param mixed[] &$options The options.
* @return bool
*/
public static function onUserLoadOptions( User $user, array &$options )
{
@@ -215,8 +226,8 @@
* @todo This is a bit icky. Need to decide if we really want to do
this.
* @todo If someone explicitly enables, gets admin rights, gets
de-admined,
* this will then disable the preference, which is definitely
non-ideal.
- * @param $user User
- * @param &$options array
+ * @param User $user The user that is being saved.
+ * @param mixed[] &$options The options.
* @return bool
*/
public static function onUserSaveOptions( User $user, array &$options )
{
diff --git a/LoginNotify_body.php b/LoginNotify_body.php
index 8abe5f2..3e1fb64 100644
--- a/LoginNotify_body.php
+++ b/LoginNotify_body.php
@@ -26,15 +26,14 @@
private $config;
/** @var LoggerInterface Usually instance of LoginNotify log */
private $log;
- /** @var Salt for cookie hash */
+ /** @var string|boolean Salt for cookie hash */
private $gSalt;
/**
* Constructor
*
- * @param $cfg Config Optional. Set if you have handy.
- * @param $cache BagOStuff Optional. Only set if you want to override
default
- * caching behaviour.
+ * @param Config $cfg Optional. Set if you have handy.
+ * @param BagOStuff $cache Optional. Only set if you want to override
default caching behaviour.
*/
public function __construct( Config $cfg = null, BagOStuff $cache =
null ) {
if ( !$cache ) {
@@ -59,6 +58,10 @@
$this->log = $log;
}
+ /**
+ * Set the logger.
+ * @param LoggerInterface $logger The logger object.
+ */
public function setLogger( LoggerInterface $logger ) {
$this->log = $logger;
}
@@ -345,7 +348,7 @@
*
* It is expected this be called upon successful log in.
*
- * @param $user User The user in question.
+ * @param User $user The user in question.
*/
public function setCurrentAddressAsKnown( User $user ) {
$this->cacheLoginIP( $user );
@@ -353,9 +356,9 @@
}
/**
- * Cache the current IP subnet as being known location for user
+ * Cache the current IP subnet as being a known location for the given
user.
*
- * @param $user User
+ * @param User $user The user.
*/
private function cacheLoginIP( User $user ) {
// For simplicity, this only stores the last IP subnet used.
@@ -365,15 +368,15 @@
if ( $expiry !== false ) {
$ipPrefix = $this->getIPNetwork(
$user->getRequest()->getIP() );
$key = $this->getKey( $user, 'prevSubnet' );
- $res = $this->cache->set( $key, $ipPrefix, $expiry );
+ $this->cache->set( $key, $ipPrefix, $expiry );
}
}
/**
* Check if a certain user is in the cookie.
*
- * @param $user User User in question
- * @return Mixed true, false or self::NO_INFO_AVAILABLE.
+ * @param User $user User in question
+ * @return boolean|integer Either true, false, or
self::NO_INFO_AVAILABLE.
*/
private function checkUserInCookie( User $user ) {
$cookie = $this->getPrevLoginCookie( $user->getRequest() );
@@ -402,8 +405,9 @@
* remove any previous instances of the current user, and remove older
user
* references, if there is too many records.
*
- * @param $user User User that person is attempting to log in as
- * @param $cookie String A cookie, which has records separated by '!'
+ * @param user $user User that person is attempting to log in as.
+ * @param string $cookie A cookie, which has records separated by '!'.
+ * @return array Element 0 is boolean (user seen before?), 1 is the new
cookie value.
*/
private function checkAndGenerateCookie( User $user, $cookie ) {
$userSeenBefore = false;
@@ -607,10 +611,10 @@
/**
* Clear attempt counter for user.
*
- * When a user succesfully logs in, we start back from 0, as
+ * When a user successfully logs in, we start back from 0, as
* otherwise a mistake here and there will trigger the warning.
*
- * @param $user User
+ * @param user $user The user for whom to clear the attempt counter.
*/
public function clearCounters( User $user ) {
$cache = $this->cache;
@@ -624,7 +628,7 @@
/**
* On login failure, record failure and maybe send notice
*
- * @param $user User The user whose account was attempted to log into
+ * @param User $user The user whose account was attempted to log into.
*/
public function recordFailure( User $user ) {
$fromKnownIP = $this->isFromKnownIP( $user );
@@ -636,9 +640,9 @@
}
/**
- * Send a notice on successful login if not known ip
+ * Send a notice on successful login from an unknown IP.
*
- * @param $user User Account in question
+ * @param User $user User account in question.
*/
public function sendSuccessNotice( User $user ) {
if ( $this->config->get( 'LoginNotifyEnableOnSuccess' )
--
To view, visit https://gerrit.wikimedia.org/r/344301
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings
Gerrit-MessageType: newchange
Gerrit-Change-Id: I06b7fc3a9fe09e412b3200b597ce01ef7e7d5ae3
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/extensions/LoginNotify
Gerrit-Branch: master
Gerrit-Owner: Samwilson <s...@samwilson.id.au>
_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits
