r38622 MediaWiki - Code Review archive

Repository:	MediaWiki
Revision:	< r38621‎ \| r38622 \| r38623 >
Date:	13:42, 5 August 2008
Author:	krimpet
Status:	old
Tags:
Comment:	Documented User.php in depth; added useful aliases to Doxyfile
Modified paths:	/trunk/phase3/includes/User.php (modified) (history) /trunk/phase3/maintenance/Doxyfile (modified) (history)

Diff [purge]

Index: trunk/phase3/maintenance/Doxyfile
—	—	@@ -1,4 +1,4 @@
2		~~-# Doxyfile 1.5.1~~
	2	+# Doxyfile 1.5.5
3	3
4	4	#
5	5	# Some placeholders have been added for MediaWiki usage:
—	—	@@ -7,6 +7,8 @@
8	8	# {{STRIP_FROM_PATH}}
9	9	# {{SVNSTAT}}
10	10	# {{INPUT}}
	11	+#
	12	+# A number of MediaWiki-specific aliases are near the end of this file.
11	13
12	14	#---------------------------------------------------------------------------
13	15	# Project related configuration options
—	—	@@ -16,7 +18,6 @@
17	19	OUTPUT_DIRECTORY = {{OUTPUT_DIRECTORY}}
18	20	CREATE_SUBDIRS = NO
19	21	OUTPUT_LANGUAGE = English
20		~~-USE_WINDOWS_ENCODING = NO~~
21	22	BRIEF_MEMBER_DESC = YES
22	23	REPEAT_BRIEF = YES
23	24	ABBREVIATE_BRIEF = "The $name class" \
—	—	@@ -42,11 +43,11 @@
43	44	INHERIT_DOCS = YES
44	45	SEPARATE_MEMBER_PAGES = NO
45	46	TAB_SIZE = 4
46		~~-ALIASES =~~
	47	+#ALIASES =
47	48	OPTIMIZE_OUTPUT_FOR_C = NO
48	49	OPTIMIZE_OUTPUT_JAVA = NO
49	50	BUILTIN_STL_SUPPORT = NO
50		~~-DISTRIBUTE_GROUP_DOC = NO~~
	51	+DISTRIBUTE_GROUP_DOC = YES
51	52	SUBGROUPING = YES
52	53	#---------------------------------------------------------------------------
53	54	# Build related configuration options
—	—	@@ -268,8 +269,6 @@
269	270	DOT_IMAGE_FORMAT = png
270	271	DOT_PATH =
271	272	DOTFILE_DIRS =
272		~~-MAX_DOT_GRAPH_WIDTH = 1024~~
273		~~-MAX_DOT_GRAPH_HEIGHT = 1024~~
274	273	MAX_DOT_GRAPH_DEPTH = 1000
275	274	DOT_TRANSPARENT = NO
276	275	DOT_MULTI_TARGETS = NO
—	—	@@ -279,3 +278,16 @@
280	279	# Configuration::additions related to the search engine
281	280	#---------------------------------------------------------------------------
282	281	SEARCHENGINE = NO
	282	+
	283	+ALIASES = "type{1}=<b> \1 </b>:" \
	284	+ "2types{2}=<b> \1 </b> or <b> \2 </b>:" \
	285	+ "3types{3}=<b> \1 </b>, <b> \2 </b>, or <b> \3 </b>:" \
	286	+ "arrayof{2}=<b> Array </b> of \2" \
	287	+ "null=\type{Null}" \
	288	+ "boolean=\type{Boolean}" \
	289	+ "bool=\boolean" \
	290	+ "integer=\type{Integer}" \
	291	+ "int=\integer" \
	292	+ "string=\type{String}" \
	293	+ "str=\string" \
	294	+ "mixed=\type{Mixed}"
\ No newline at end of file
Index: trunk/phase3/includes/User.php
—	—	@@ -1,20 +1,29 @@
2	2	<?php
3	3	/**
4		~~- * See user.txt~~
	4	+ * Implements the User class for the %MediaWiki software.
5	5	* @file
6	6	*/
7	7
8		~~-# Number of characters in user_token field~~
	8	+/**
	9	+ * \int Number of characters in user_token field.
	10	+ * @ingroup Constants
	11	+ */
9	12	define( 'USER_TOKEN_LENGTH', 32 );
10	13
11		~~-# Serialized record version~~
	14	+/**
	15	+ * \int Serialized record version.
	16	+ * @ingroup Constants
	17	+ */
12	18	define( 'MW_USER_VERSION', 6 );
13	19
14		~~-# Some punctuation to prevent editing from broken text-mangling proxies.~~
	20	+/**
	21	+ * \string Some punctuation to prevent editing from broken text-mangling proxies.
	22	+ * @ingroup Constants
	23	+ */
15	24	define( 'EDIT_TOKEN_SUFFIX', '+\\' );
16	25
17	26	/**
18		~~- * Thrown by User::setPassword() on error~~
	27	+ * Thrown by User::setPassword() on error.
19	28	* @ingroup Exception
20	29	*/
21	30	class PasswordError extends MWException {
—	—	@@ -34,11 +43,13 @@
35	44	class User {
36	45
37	46	/**
38		~~- * A list of default user toggles, i.e. boolean user preferences that are~~
39		~~- * displayed by Special:Preferences as checkboxes. This list can be~~
40		~~- * extended via the UserToggles hook or $wgContLang->getExtraUserToggles().~~
	47	+ * \arrayof{\string} A list of default user toggles, i.e., boolean user
	48	+ * preferences that are displayed by Special:Preferences as checkboxes.
	49	+ * This list can be extended via the UserToggles hook or by
	50	+ * $wgContLang::getExtraUserToggles().
	51	+ * @showinitializer
41	52	*/
42		~~- static public $mToggles = array(~~
	53	+ public static $mToggles = array(
43	54	'highlightbroken',
44	55	'justify',
45	56	'hideminor',
—	—	@@ -80,12 +91,13 @@
81	92	);
82	93
83	94	/**
84		~~- * List of member variables which are saved to the shared cache (memcached).~~
85		~~- * Any operation which changes the corresponding database fields must~~
86		~~- * call a cache-clearing function.~~
	95	+ * \arrayof{\string} List of member variables which are saved to the
	96	+ * shared cache (memcached). Any operation which changes the
	97	+ * corresponding database fields must call a cache-clearing function.
	98	+ * @showinitializer
87	99	*/
88	100	static $mCacheVars = array(
89		~~- # user table~~
	101	+ // user table
90	102	'mId',
91	103	'mName',
92	104	'mRealName',
—	—	@@ -101,13 +113,15 @@
102	114	'mEmailTokenExpires',
103	115	'mRegistration',
104	116	'mEditCount',
105		~~- # user_group table~~
	117	+ // user_group table
106	118	'mGroups',
107	119	);
108	120
109	121	/**
110		~~- * Core rights~~
111		~~- * Each of these should have a corresponding message of the form "right-$right"~~
	122	+ * \arrayof{\string} Core rights.
	123	+ * Each of these should have a corresponding message of the form
	124	+ * "right-$right".
	125	+ * @showinitializer
112	126	*/
113	127	static $mCoreRights = array(
114	128	'apihighlimits',
—	—	@@ -150,47 +164,56 @@
151	165	'upload_by_url',
152	166	'userrights',
153	167	);
	168	+ /**
	169	+ * \string Cached results of getAllRights()
	170	+ */
154	171	static $mAllRights = false;
155	172
156		- /**
157		~~- * The cache variable declarations~~
158		~~- */~~
	173	+ /** @name Cache variables */
	174	+ //@{
159	175	var $mId, $mName, $mRealName, $mPassword, $mNewpassword, $mNewpassTime,
160	176	$mEmail, $mOptions, $mTouched, $mToken, $mEmailAuthenticated,
161	177	$mEmailToken, $mEmailTokenExpires, $mRegistration, $mGroups;
	178	+ //@}
162	179
163	180	/**
164		~~- * Whether the cache variables have been loaded~~
	181	+ * \bool Whether the cache variables have been loaded.
165	182	*/
166	183	var $mDataLoaded;
167	184
168	185	/**
169		~~- * Initialisation data source if mDataLoaded==false. May be one of:~~
170		~~- * defaults anonymous user initialised from class defaults~~
171		~~- * name initialise from mName~~
172		~~- * id initialise from mId~~
173		~~- * session log in from cookies or session if possible~~
	186	+ * \string Initialization data source if mDataLoaded==false. May be one of:
	187	+ * - 'defaults' anonymous user initialised from class defaults
	188	+ * - 'name' initialise from mName
	189	+ * - 'id' initialise from mId
	190	+ * - 'session' log in from cookies or session if possible
174	191	*
175	192	* Use the User::newFrom*() family of functions to set this.
176	193	*/
177	194	var $mFrom;
178	195
179		- /**
180		~~- * Lazy-initialised variables, invalidated with clearInstanceCache~~
181		~~- */~~
	196	+ /** @name Lazy-initialized variables, invalidated with clearInstanceCache */
	197	+ //@{
182	198	var $mNewtalk, $mDatePreference, $mBlockedby, $mHash, $mSkin, $mRights,
183	199	$mBlockreason, $mBlock, $mEffectiveGroups;
	200	+ //@}
184	201
185	202	/**
186		~~- * Lightweight constructor for anonymous user~~
187		~~- * Use the User::newFrom* factory functions for other kinds of users~~
	203	+ * Lightweight constructor for an anonymous user.
	204	+ * Use the User::newFrom* factory functions for other kinds of users.
	205	+ *
	206	+ * @see newFromName()
	207	+ * @see newFromId()
	208	+ * @see newFromConfirmationCode()
	209	+ * @see newFromSession()
	210	+ * @see newFromRow()
188	211	*/
189	212	function User() {
190	213	$this->clearInstanceCache( 'defaults' );
191	214	}
192	215
193	216	/**
194		~~- * Load the user table data for this object from the source given by mFrom~~
	217	+ * Load the user table data for this object from the source given by mFrom.
195	218	*/
196	219	function load() {
197	220	if ( $this->mDataLoaded ) {
—	—	@@ -227,8 +250,8 @@
228	251	}
229	252
230	253	/**
231		~~- * Load user table data given mId~~
232		~~- * @return false if the ID does not exist, true otherwise~~
	254	+ * Load user table data, given mId has already been set.
	255	+ * @return \bool false if the ID does not exist, true otherwise
233	256	* @private
234	257	*/
235	258	function loadFromId() {
—	—	@@ -283,6 +306,10 @@
284	307	global $wgMemc;
285	308	$wgMemc->set( $key, $data );
286	309	}
	310	+
	311	+
	312	+ /** @name newFrom() static factory methods /
	313	+ //@{
287	314
288	315	/**
289	316	* Static factory method for creation from username.
—	—	@@ -290,14 +317,14 @@
291	318	* This is slightly less efficient than newFromId(), so use newFromId() if
292	319	* you have both an ID and a name handy.
293	320	*
294		~~- * @param $name String: username, validated by Title:newFromText()~~
295		~~- * @param $validate Mixed: validate username. Takes the same parameters as~~
	321	+ * @param $name \string Username, validated by Title::newFromText()
	322	+ * @param $validate \mixed Validate username. Takes the same parameters as
296	323	* User::getCanonicalName(), except that true is accepted as an alias
297	324	* for 'valid', for BC.
298	325	*
299		~~- * @return User object, or null if the username is invalid. If the username~~
300		~~- * is not present in the database, the result will be a user object with~~
301		~~- * a name, zero user ID and default settings.~~
	326	+ * @return \type{User} The User object, or null if the username is invalid. If the
	327	+ * username is not present in the database, the result will be a user object
	328	+ * with a name, zero user ID and default settings.
302	329	*/
303	330	static function newFromName( $name, $validate = 'valid' ) {
304	331	if ( $validate === true ) {
—	—	@@ -315,6 +342,12 @@
316	343	}
317	344	}
318	345
	346	+ /**
	347	+ * Static factory method for creation from a given user ID.
	348	+ *
	349	+ * @param $id \int Valid user ID
	350	+ * @return \type{User} The corresponding User object
	351	+ */
319	352	static function newFromId( $id ) {
320	353	$u = new User;
321	354	$u->mId = $id;
—	—	@@ -329,8 +362,8 @@
330	363	*
331	364	* If the code is invalid or has expired, returns NULL.
332	365	*
333		~~- * @param $code string~~
334		~~- * @return User~~
	366	+ * @param $code \string Confirmation code
	367	+ * @return \type{User}
335	368	*/
336	369	static function newFromConfirmationCode( $code ) {
337	370	$dbr = wfGetDB( DB_SLAVE );
—	—	@@ -349,7 +382,7 @@
350	383	* Create a new user object using data from session or cookies. If the
351	384	* login credentials are invalid, the result is an anonymous user.
352	385	*
353		~~- * @return User~~
	386	+ * @return \type{User}
354	387	*/
355	388	static function newFromSession() {
356	389	$user = new User;
—	—	@@ -360,17 +393,22 @@
361	394	/**
362	395	* Create a new user object from a user row.
363	396	* The row should have all fields from the user table in it.
	397	+ * @param $row array A row from the user table
	398	+ * @return \type{User}
364	399	*/
365	400	static function newFromRow( $row ) {
366	401	$user = new User;
367	402	$user->loadFromRow( $row );
368	403	return $user;
369	404	}
	405	+
	406	+ //@}
	407	+
370	408
371	409	/**
372		~~- * Get username given an id.~~
373		~~- * @param $id Integer: database user id~~
374		~~- * @return string Nickname of a user~~
	410	+ * Get the username corresponding to a given user ID
	411	+ * @param $id \int User ID
	412	+ * @return \string The corresponding username
375	413	*/
376	414	static function whoIs( $id ) {
377	415	$dbr = wfGetDB( DB_SLAVE );
—	—	@@ -378,10 +416,10 @@
379	417	}
380	418
381	419	/**
382		~~- * Get the real name of a user given their identifier~~
	420	+ * Get the real name of a user given their user ID
383	421	*
384		~~- * @param $id Int: database user id~~
385		~~- * @return string Real name of a user~~
	422	+ * @param $id \int User ID
	423	+ * @return \string The corresponding user's real name
386	424	*/
387	425	static function whoIsReal( $id ) {
388	426	$dbr = wfGetDB( DB_SLAVE );
—	—	@@ -390,8 +428,8 @@
391	429
392	430	/**
393	431	* Get database id given a user name
394		~~- * @param $name String: nickname of a user~~
395		~~- * @return integer\|null Database user id (null: if non existent~~
	432	+ * @param $name \string Username
	433	+ * @return \2types{\int,\null} The corresponding user's ID, or null if user is nonexistent
396	434	* @static
397	435	*/
398	436	static function idFromName( $name ) {
—	—	@@ -423,8 +461,8 @@
424	462	* addresses like this, if we allowed accounts like this to be created
425	463	* new users could get the old edits of these anonymous users.
426	464	*
427		~~- * @param $name String: nickname of a user~~
428		~~- * @return bool~~
	465	+ * @param $name \string
	466	+ * @return \bool
429	467	*/
430	468	static function isIP( $name ) {
431	469	return preg_match('/^\d{1,3}\.\d{1,3}\.\d{1,3}\.(?:xxx\|\d{1,3})$/',$name) \|\| IP::isIPv6($name);
—	—	@@ -438,8 +476,8 @@
439	477	* is longer than the maximum allowed username size or doesn't begin with
440	478	* a capital letter.
441	479	*
442		~~- * @param $name string~~
443		~~- * @return bool~~
	480	+ * @param $name \string
	481	+ * @return \bool
444	482	*/
445	483	static function isValidUserName( $name ) {
446	484	global $wgContLang, $wgMaxNameChars;
—	—	@@ -492,8 +530,8 @@
493	531	* If an account already exists in this form, login will be blocked
494	532	* by a failure to pass this function.
495	533	*
496		~~- * @param $name string~~
497		~~- * @return bool~~
	534	+ * @param $name \string
	535	+ * @return \bool
498	536	*/
499	537	static function isUsableName( $name ) {
500	538	global $wgReservedUsernames;
—	—	@@ -524,8 +562,8 @@
525	563	* rather than in isValidUserName() to avoid disrupting
526	564	* existing accounts.
527	565	*
528		~~- * @param $name string~~
529		~~- * @return bool~~
	566	+ * @param $name \string
	567	+ * @return \bool
530	568	*/
531	569	static function isCreatableName( $name ) {
532	570	return
—	—	@@ -538,8 +576,8 @@
539	577	/**
540	578	* Is the input a valid password for this user?
541	579	*
542		~~- * @param $password String: desired password~~
543		~~- * @return bool~~
	580	+ * @param $password \string Desired password
	581	+ * @return \bool
544	582	*/
545	583	function isValidPassword( $password ) {
546	584	global $wgMinimalPasswordLength, $wgContLang;
—	—	@@ -556,7 +594,7 @@
557	595	}
558	596
559	597	/**
560		~~- * Does a string look like an email address?~~
	598	+ * Does a string look like an e-mail address?
561	599	*
562	600	* There used to be a regular expression here, it got removed because it
563	601	* rejected valid addresses. Actually just check if there is '@' somewhere
—	—	@@ -564,8 +602,8 @@
565	603	*
566	604	* @todo Check for RFC 2822 compilance (bug 959)
567	605	*
568		~~- * @param $addr String: email address~~
569		~~- * @return bool~~
	606	+ * @param $addr \string E-mail address
	607	+ * @return \bool
570	608	*/
571	609	public static function isValidEmailAddr( $addr ) {
572	610	$result = null;
—	—	@@ -579,12 +617,12 @@
580	618	/**
581	619	* Given unvalidated user input, return a canonical username, or false if
582	620	* the username is invalid.
583		~~- * @param $name string~~
584		~~- * @param $validate Mixed: type of validation to use:~~
585		~~- * false No validation~~
586		~~- * 'valid' Valid for batch processes~~
587		~~- * 'usable' Valid for batch processes and login~~
588		~~- * 'creatable' Valid for batch processes, login and account creation~~
	621	+ * @param $name \string User input
	622	+ * @param $validate \2types{\string,\bool} Type of validation to use:
	623	+ * - false No validation
	624	+ * - 'valid' Valid for batch processes
	625	+ * - 'usable' Valid for batch processes and login
	626	+ * - 'creatable' Valid for batch processes, login and account creation
589	627	*/
590	628	static function getCanonicalName( $name, $validate = 'valid' ) {
591	629	# Force usernames to capital
—	—	@@ -634,11 +672,10 @@
635	673
636	674	/**
637	675	* Count the number of edits of a user
	676	+ * @todo It should not be static and some day should be merged as proper member function / deprecated -- domas
638	677	*
639		~~- * It should not be static and some day should be merged as proper member function / deprecated -- domas~~
640		- *
641		~~- * @param $uid Int: the user ID to check~~
642		~~- * @return int~~
	678	+ * @param $uid \int User ID to check
	679	+ * @return \int The user's edit count
643	680	*/
644	681	static function edits( $uid ) {
645	682	wfProfileIn( __METHOD__ );
—	—	@@ -674,7 +711,7 @@
675	712	* Return a random password. Sourced from mt_rand, so it's not particularly secure.
676	713	* @todo hash random numbers to improve security, like generateToken()
677	714	*
678		~~- * @return string~~
	715	+ * @return \string
679	716	*/
680	717	static function randomPassword() {
681	718	global $wgMinimalPasswordLength;
—	—	@@ -691,9 +728,10 @@
692	729	}
693	730
694	731	/**
695		~~- * Set cached properties to default. Note: this no longer clears~~
696		~~- * uncached lazy-initialised properties. The constructor does that instead.~~
	732	+ * Set cached properties to default.
697	733	*
	734	+ * @note This no longer clears uncached lazy-initialised properties;
	735	+ * the constructor does that instead.
698	736	* @private
699	737	*/
700	738	function loadDefaults( $name = false ) {
—	—	@@ -728,8 +766,7 @@
729	767	}
730	768
731	769	/**
732		~~- * Initialise php session~~
733		~~- * @deprecated use wfSetupSession()~~
	770	+ * @deprecated Use wfSetupSession().
734	771	*/
735	772	function SetupSession() {
736	773	wfDeprecated( __METHOD__ );
—	—	@@ -738,8 +775,8 @@
739	776
740	777	/**
741	778	* Load user data from the session or login cookie. If there are no valid
742		~~- * credentials, initialises the user as an anon.~~
743		~~- * @return true if the user is logged in, false otherwise~~
	779	+ * credentials, initialises the user as an anonymous user.
	780	+ * @return \bool True if the user is logged in, false otherwise.
744	781	*/
745	782	private function loadFromSession() {
746	783	global $wgMemc, $wgCookiePrefix;
—	—	@@ -806,10 +843,10 @@
807	844	}
808	845
809	846	/**
810		~~- * Load user and user_group data from the database~~
811		~~- * $this->mId must be set, this is how the user is identified.~~
	847	+ * Load user and user_group data from the database.
	848	+ * $this::mId must be set, this is how the user is identified.
812	849	*
813		~~- * @return true if the user exists, false if the user is anonymous~~
	850	+ * @return \bool True if the user exists, false if the user is anonymous
814	851	* @private
815	852	*/
816	853	function loadFromDatabase() {
—	—	@@ -840,7 +877,9 @@
841	878	}
842	879
843	880	/**
844		~~- * Initialise the user object from a row from the user table~~
	881	+ * Initialize this object from a row from the user table.
	882	+ *
	883	+ * @param $row \arrayof{\mixed} Row from the user table to load.
845	884	*/
846	885	function loadFromRow( $row ) {
847	886	$this->mDataLoaded = true;
—	—	@@ -865,7 +904,7 @@
866	905	}
867	906
868	907	/**
869		~~- * Load the groups from the database if they aren't already loaded~~
	908	+ * Load the groups from the database if they aren't already loaded.
870	909	* @private
871	910	*/
872	911	function loadGroups() {
—	—	@@ -884,8 +923,8 @@
885	924
886	925	/**
887	926	* Clear various cached data stored in this object.
888		~~- * @param $reloadFrom String: reload user and user_groups table data from a~~
889		~~- * given source. May be "name", "id", "defaults", "session" or false for~~
	927	+ * @param $reloadFrom \string Reload user and user_groups table data from a
	928	+ * given source. May be "name", "id", "defaults", "session", or false for
890	929	* no reload.
891	930	*/
892	931	function clearInstanceCache( $reloadFrom = false ) {
—	—	@@ -906,9 +945,8 @@
907	946	/**
908	947	* Combine the language default options with any site-specific options
909	948	* and add the default language variants.
910		~~- * Not really private cause it's called by Language class~~
911		~~- * @return array~~
912		~~- * @private~~
	949	+ *
	950	+ * @return \arrayof{\string} Array of options
913	951	*/
914	952	static function getDefaultOptions() {
915	953	global $wgNamespacesToBeSearchedDefault;
—	—	@@ -934,8 +972,8 @@
935	973	/**
936	974	* Get a given default option value.
937	975	*
938		~~- * @param $opt string~~
939		~~- * @return string~~
	976	+ * @param $opt \string Name of option to retrieve
	977	+ * @return \string
940	978	*/
941	979	public static function getDefaultOption( $opt ) {
942	980	$defOpts = self::getDefaultOptions();
—	—	@@ -948,7 +986,7 @@
949	987
950	988	/**
951	989	* Get a list of user toggle names
952		~~- * @return array~~
	990	+ * @return \arrayof{\string}
953	991	*/
954	992	static function getToggles() {
955	993	global $wgContLang;
—	—	@@ -961,7 +999,7 @@
962	1000	/**
963	1001	* Get blocking information
964	1002	* @private
965		~~- * @param $bFromSlave Bool: specify whether to check slave or master. To~~
	1003	+ * @param $bFromSlave \bool Whether to check the slave database first. To
966	1004	* improve performance, non-critical checks are done
967	1005	* against slaves. Check when actually saving should be
968	1006	* done against master.
—	—	@@ -1032,6 +1070,12 @@
1033	1071	wfProfileOut( __METHOD__ );
1034	1072	}
1035	1073
	1074	+ /**
	1075	+ * Whether the given IP is in the SORBS blacklist.
	1076	+ *
	1077	+ * @param $ip \string IP to check
	1078	+ * @return \bool
	1079	+ */
1036	1080	function inSorbsBlacklist( $ip ) {
1037	1081	global $wgEnableSorbs, $wgSorbsUrl;
1038	1082
—	—	@@ -1039,6 +1083,13 @@
1040	1084	$this->inDnsBlacklist( $ip, $wgSorbsUrl );
1041	1085	}
1042	1086
	1087	+ /**
	1088	+ * Whether the given IP is in a given DNS blacklist.
	1089	+ *
	1090	+ * @param $ip \string IP to check
	1091	+ * @param $base \string URL of the DNS blacklist
	1092	+ * @return \bool
	1093	+ */
1043	1094	function inDnsBlacklist( $ip, $base ) {
1044	1095	wfProfileIn( __METHOD__ );
1045	1096
—	—	@@ -1071,7 +1122,7 @@
1072	1123	/**
1073	1124	* Is this user subject to rate limiting?
1074	1125	*
1075		~~- * @return bool~~
	1126	+ * @return \bool
1076	1127	*/
1077	1128	public function isPingLimitable() {
1078	1129	global $wgRateLimitsExcludedGroups;
—	—	@@ -1086,10 +1137,11 @@
1087	1138	* Primitive rate limits: enforce maximum actions per time period
1088	1139	* to put a brake on flooding.
1089	1140	*
1090		~~- * Note: when using a shared cache like memcached, IP-address~~
	1141	+ * @note When using a shared cache like memcached, IP-address
1091	1142	* last-hit counters will be shared across wikis.
1092	1143	*
1093		~~- * @return bool true if a rate limiter was tripped~~
	1144	+ * @param $action \string Action to enforce; 'edit' if unspecified
	1145	+ * @return \bool True if a rate limiter was tripped
1094	1146	*/
1095	1147	function pingLimiter( $action='edit' ) {
1096	1148
—	—	@@ -1180,7 +1232,9 @@
1181	1233
1182	1234	/**
1183	1235	* Check if user is blocked
1184		~~- * @return bool True if blocked, false otherwise~~
	1236	+ *
	1237	+ * @param $bFromSlave \bool Whether to check the slave database instead of the master
	1238	+ * @return \bool True if blocked, false otherwise
1185	1239	*/
1186	1240	function isBlocked( $bFromSlave = true ) { // hacked from false due to horrible probs on site
1187	1241	wfDebug( "User::isBlocked: enter\n" );
—	—	@@ -1190,6 +1244,10 @@
1191	1245
1192	1246	/**
1193	1247	* Check if user is blocked from editing a particular article
	1248	+ *
	1249	+ * @param $title \string Title to check
	1250	+ * @param $bFromSlave \bool Whether to check the slave database instead of the master
	1251	+ * @return \bool True if blocked, false otherwise
1194	1252	*/
1195	1253	function isBlockedFrom( $title, $bFromSlave = false ) {
1196	1254	global $wgBlockAllowsUTEdit;
—	—	@@ -1209,8 +1267,8 @@
1210	1268	}
1211	1269
1212	1270	/**
1213		~~- * Get name of blocker~~
1214		~~- * @return string name of blocker~~
	1271	+ * If user is blocked, return the name of the user who placed the block
	1272	+ * @return \string name of blocker
1215	1273	*/
1216	1274	function blockedBy() {
1217	1275	$this->getBlockedStatus();
—	—	@@ -1218,8 +1276,8 @@
1219	1277	}
1220	1278
1221	1279	/**
1222		~~- * Get blocking reason~~
1223		~~- * @return string Blocking reason~~
	1280	+ * If user is blocked, return the specified reason for the block
	1281	+ * @return \string Blocking reason
1224	1282	*/
1225	1283	function blockedFor() {
1226	1284	$this->getBlockedStatus();
—	—	@@ -1227,7 +1285,8 @@
1228	1286	}
1229	1287
1230	1288	/**
1231		~~- * Get the user ID. Returns 0 if the user is anonymous or nonexistent.~~
	1289	+ * Get the user's ID.
	1290	+ * @return \int The user's ID; 0 if the user is anonymous or nonexistent
1232	1291	*/
1233	1292	function getId() {
1234	1293	if( $this->mId === null and $this->mName !== null
—	—	@@ -1242,7 +1301,8 @@
1243	1302	}
1244	1303
1245	1304	/**
1246		~~- * Set the user and reload all fields according to that ID~~
	1305	+ * Set the user and reload all fields according to a given ID
	1306	+ * @param $v \int User ID to reload
1247	1307	*/
1248	1308	function setId( $v ) {
1249	1309	$this->mId = $v;
—	—	@@ -1250,7 +1310,8 @@
1251	1311	}
1252	1312
1253	1313	/**
1254		~~- * Get the user name, or the IP for anons~~
	1314	+ * Get the user name, or the IP of an anonymous user
	1315	+ * @return \string
1255	1316	*/
1256	1317	function getName() {
1257	1318	if ( !$this->mDataLoaded && $this->mFrom == 'name' ) {
—	—	@@ -1275,8 +1336,9 @@
1276	1337	* address for an anonymous user to something other than the current
1277	1338	* remote IP.
1278	1339	*
1279		~~- * User::newFromName() has rougly the same function, when the named user~~
	1340	+ * @note User::newFromName() has rougly the same function, when the named user
1280	1341	* does not exist.
	1342	+ * @param $str \string New user name to set
1281	1343	*/
1282	1344	function setName( $str ) {
1283	1345	$this->load();
—	—	@@ -1284,13 +1346,17 @@
1285	1347	}
1286	1348
1287	1349	/**
1288		~~- * Return the title dbkey form of the name, for eg user pages.~~
1289		~~- * @return string~~
	1350	+ * Get the user's name escaped by underscores.
	1351	+ * @return \string
1290	1352	*/
1291	1353	function getTitleKey() {
1292	1354	return str_replace( ' ', '_', $this->getName() );
1293	1355	}
1294	1356
	1357	+ /**
	1358	+ * Check if the user has new messages.
	1359	+ * @return \bool True if the user has new messages
	1360	+ */
1295	1361	function getNewtalk() {
1296	1362	$this->load();
1297	1363
—	—	@@ -1322,6 +1388,7 @@
1323	1389
1324	1390	/**
1325	1391	* Return the talk page(s) this user has new messages on.
	1392	+ * @return \arrayof{\string} Array of page URLs
1326	1393	*/
1327	1394	function getNewMessageLinks() {
1328	1395	$talks = array();
—	—	@@ -1337,13 +1404,13 @@
1338	1405
1339	1406
1340	1407	/**
1341		~~- * Perform a user_newtalk check, uncached.~~
1342		~~- * Use getNewtalk for a cached check.~~
	1408	+ * Internal uncached check for new messages
1343	1409	*
1344		~~- * @param $field string~~
1345		~~- * @param $id mixed~~
1346		~~- * @param $fromMaster Bool: true to fetch from the master, false for a slave~~
1347		~~- * @return bool~~
	1410	+ * @see getNewtalk()
	1411	+ * @param $field \string 'user_ip' for anonymous users, 'user_id' otherwise
	1412	+ * @param $id \2types{\string,\int} User's IP address for anonymous users, User ID otherwise
	1413	+ * @param $fromMaster \bool true to fetch from the master, false for a slave
	1414	+ * @return \bool True if the user has new messages
1348	1415	* @private
1349	1416	*/
1350	1417	function checkNewtalk( $field, $id, $fromMaster = false ) {
—	—	@@ -1358,9 +1425,10 @@
1359	1426	}
1360	1427
1361	1428	/**
1362		~~- * Add or update the~~
1363		~~- * @param $field string~~
1364		~~- * @param $id mixed~~
	1429	+ * Add or update the new messages flag
	1430	+ * @param $field \string 'user_ip' for anonymous users, 'user_id' otherwise
	1431	+ * @param $id \2types{\string,\int} User's IP address for anonymous users, User ID otherwise
	1432	+ * @return \bool True if successful, false otherwise
1365	1433	* @private
1366	1434	*/
1367	1435	function updateNewtalk( $field, $id ) {
—	—	@@ -1380,8 +1448,9 @@
1381	1449
1382	1450	/**
1383	1451	* Clear the new messages flag for the given user
1384		~~- * @param $field string~~
1385		~~- * @param $id mixed~~
	1452	+ * @param $field \string 'user_ip' for anonymous users, 'user_id' otherwise
	1453	+ * @param $id \2types{\string,\int} User's IP address for anonymous users, User ID otherwise
	1454	+ * @return \bool True if successful, false otherwise
1386	1455	* @private
1387	1456	*/
1388	1457	function deleteNewtalk( $field, $id ) {
—	—	@@ -1400,7 +1469,7 @@
1401	1470
1402	1471	/**
1403	1472	* Update the 'You have new messages!' status.
1404		~~- * @param $val bool~~
	1473	+ * @param $val \bool Whether the user has new messages
1405	1474	*/
1406	1475	function setNewtalk( $val ) {
1407	1476	if( wfReadOnly() ) {
—	—	@@ -1439,6 +1508,7 @@
1440	1509	/**
1441	1510	* Generate a current or new-future timestamp to be stored in the
1442	1511	* user_touched field when we update things.
	1512	+ * @return \string Timestamp in TS_MW format
1443	1513	*/
1444	1514	private static function newTouchedTimestamp() {
1445	1515	global $wgClockSkewFudge;
—	—	@@ -1479,13 +1549,17 @@
1480	1550	}
1481	1551	}
1482	1552
	1553	+ /**
	1554	+ * Validate the cache for this account.
	1555	+ * @param $timestamp \string A timestamp in TS_MW format
	1556	+ */
1483	1557	function validateCache( $timestamp ) {
1484	1558	$this->load();
1485	1559	return ($timestamp >= $this->mTouched);
1486	1560	}
1487	1561
1488	1562	/**
1489		~~- * Set the password and reset the random token~~
	1563	+ * Set the password and reset the random token.
1490	1564	* Calls through to authentication plugin if necessary;
1491	1565	* will have no effect if the auth plugin refuses to
1492	1566	* pass the change through or if the legal password
—	—	@@ -1495,7 +1569,7 @@
1496	1570	* wipes it, so the account cannot be logged in until
1497	1571	* a new password is set, for instance via e-mail.
1498	1572	*
1499		~~- * @param $str string~~
	1573	+ * @param $str \string New password to set
1500	1574	* @throws PasswordError on failure
1501	1575	*/
1502	1576	function setPassword( $str ) {
—	—	@@ -1523,10 +1597,9 @@
1524	1598	}
1525	1599
1526	1600	/**
1527		~~- * Set the password and reset the random token no matter~~
1528		~~- * what.~~
	1601	+ * Set the password and reset the random token unconditionally.
1529	1602	*
1530		~~- * @param $str string~~
	1603	+ * @param $str \string New password to set
1531	1604	*/
1532	1605	function setInternalPassword( $str ) {
1533	1606	$this->load();
—	—	@@ -1542,6 +1615,10 @@
1543	1616	$this->mNewpassTime = null;
1544	1617	}
1545	1618
	1619	+ /**
	1620	+ * Get the user's current token.
	1621	+ * @return \string
	1622	+ */
1546	1623	function getToken() {
1547	1624	$this->load();
1548	1625	return $this->mToken;
—	—	@@ -1550,6 +1627,8 @@
1551	1628	/**
1552	1629	* Set the random token (used for persistent authentication)
1553	1630	* Called from loadDefaults() among other places.
	1631	+ *
	1632	+ * @param $token \string If specified, set the token to this value
1554	1633	* @private
1555	1634	*/
1556	1635	function setToken( $token = false ) {
—	—	@@ -1568,7 +1647,13 @@
1569	1648	$this->mToken = $token;
1570	1649	}
1571	1650	}
1572		-
	1651	+
	1652	+ /**
	1653	+ * Set the cookie password
	1654	+ *
	1655	+ * @param $str \string New cookie password
	1656	+ * @private
	1657	+ */
1573	1658	function setCookiePassword( $str ) {
1574	1659	$this->load();
1575	1660	$this->mCookiePassword = md5( $str );
—	—	@@ -1576,7 +1661,9 @@
1577	1662
1578	1663	/**
1579	1664	* Set the password for a password reminder or new account email
1580		~~- * Sets the user_newpass_time field if $throttle is true~~
	1665	+ *
	1666	+ * @param $str \string New password to set
	1667	+ * @param $throttle \bool If true, reset the throttle timestamp to the present
1581	1668	*/
1582	1669	function setNewpassword( $str, $throttle = true ) {
1583	1670	$this->load();
—	—	@@ -1587,8 +1674,9 @@
1588	1675	}
1589	1676
1590	1677	/**
1591		~~- * Returns true if a password reminder email has already been sent within~~
1592		~~- * the last $wgPasswordReminderResendTime hours~~
	1678	+ * Has password reminder email been sent within the last
	1679	+ * $wgPasswordReminderResendTime hours?
	1680	+ * @return \bool
1593	1681	*/
1594	1682	function isPasswordReminderThrottled() {
1595	1683	global $wgPasswordReminderResendTime;
—	—	@@ -1600,38 +1688,62 @@
1601	1689	return time() < $expiry;
1602	1690	}
1603	1691
	1692	+ /**
	1693	+ * Get the user's e-mail address
	1694	+ * @return \string
	1695	+ */
1604	1696	function getEmail() {
1605	1697	$this->load();
1606	1698	wfRunHooks( 'UserGetEmail', array( $this, &$this->mEmail ) );
1607	1699	return $this->mEmail;
1608	1700	}
1609	1701
	1702	+ /**
	1703	+ * Get the timestamp of the user's e-mail authentication
	1704	+ * @return \string TS_MW timestamp
	1705	+ */
1610	1706	function getEmailAuthenticationTimestamp() {
1611	1707	$this->load();
1612	1708	wfRunHooks( 'UserGetEmailAuthenticationTimestamp', array( $this, &$this->mEmailAuthenticated ) );
1613	1709	return $this->mEmailAuthenticated;
1614	1710	}
1615	1711
	1712	+ /**
	1713	+ * Set the user's e-mail address
	1714	+ * @param $str \string New e-mail address
	1715	+ */
1616	1716	function setEmail( $str ) {
1617	1717	$this->load();
1618	1718	$this->mEmail = $str;
1619	1719	wfRunHooks( 'UserSetEmail', array( $this, &$this->mEmail ) );
1620	1720	}
1621	1721
	1722	+ /**
	1723	+ * Get the user's real name
	1724	+ * @return \string
	1725	+ */
1622	1726	function getRealName() {
1623	1727	$this->load();
1624	1728	return $this->mRealName;
1625	1729	}
1626	1730
	1731	+ /**
	1732	+ * Set the user's real name
	1733	+ * @param $str \string New real name
	1734	+ */
1627	1735	function setRealName( $str ) {
1628	1736	$this->load();
1629	1737	$this->mRealName = $str;
1630	1738	}
1631	1739
1632	1740	/**
1633		~~- * @param $oname String: the option to check~~
1634		~~- * @param $defaultOverride String: A default value returned if the option does not exist~~
1635		~~- * @return string~~
	1741	+ * Get the user's current setting for a given option.
	1742	+ *
	1743	+ * @param $oname \string The option to check
	1744	+ * @param $defaultOverride \string A default value returned if the option does not exist
	1745	+ * @return \string User's current value for the option
	1746	+ * @see getBoolOption()
	1747	+ * @see getIntOption()
1636	1748	*/
1637	1749	function getOption( $oname, $defaultOverride = '' ) {
1638	1750	$this->load();
—	—	@@ -1649,46 +1761,41 @@
1650	1762	return $defaultOverride;
1651	1763	}
1652	1764	}
1653		-
	1765	+
1654	1766	/**
1655		~~- * Get the user's date preference, including some important migration for~~
1656		~~- * old user rows.~~
	1767	+ * Get the user's current setting for a given option, as a boolean value.
	1768	+ *
	1769	+ * @param $oname \string The option to check
	1770	+ * @return \bool User's current value for the option
	1771	+ * @see getOption()
1657	1772	*/
1658		~~- function getDatePreference() {~~
1659		~~- if ( is_null( $this->mDatePreference ) ) {~~
1660		~~- global $wgLang;~~
1661		~~- $value = $this->getOption( 'date' );~~
1662		~~- $map = $wgLang->getDatePreferenceMigrationMap();~~
1663		~~- if ( isset( $map[$value] ) ) {~~
1664		~~- $value = $map[$value];~~
1665		~~- }~~
1666		~~- $this->mDatePreference = $value;~~
1667		~~- }~~
1668		~~- return $this->mDatePreference;~~
1669		~~- }~~
1670		-
1671		- /**
1672		~~- * @param $oname String: the option to check~~
1673		~~- * @return bool False if the option is not selected, true if it is~~
1674		~~- */~~
1675	1773	function getBoolOption( $oname ) {
1676	1774	return (bool)$this->getOption( $oname );
1677	1775	}
1678	1776
	1777	+
1679	1778	/**
1680		~~- * Get an option as an integer value from the source string.~~
1681		~~- * @param $oname String: the option to check~~
1682		~~- * @param $default Int: optional value to return if option is unset/blank.~~
1683		~~- * @return int~~
	1779	+ * Get the user's current setting for a given option, as a boolean value.
	1780	+ *
	1781	+ * @param $oname \string The option to check
	1782	+ * @param $defaultOverride \int A default value returned if the option does not exist
	1783	+ * @return \int User's current value for the option
	1784	+ * @see getOption()
1684	1785	*/
1685		~~- function getIntOption( $oname, $default=0 ) {~~
	1786	+ function getIntOption( $oname, $defaultOverride=0 ) {
1686	1787	$val = $this->getOption( $oname );
1687	1788	if( $val == '' ) {
1688		~~- $val = $default;~~
	1789	+ $val = $defaultOverride;
1689	1790	}
1690	1791	return intval( $val );
1691	1792	}
1692	1793
	1794	+ /**
	1795	+ * Set the given option for a user.
	1796	+ *
	1797	+ * @param $oname \string The option to set
	1798	+ * @param $val \mixed New value to set
	1799	+ */
1693	1800	function setOption( $oname, $val ) {
1694	1801	$this->load();
1695	1802	if ( is_null( $this->mOptions ) ) {
—	—	@@ -1713,6 +1820,28 @@
1714	1821	$this->mOptions[$oname] = $val;
1715	1822	}
1716	1823
	1824	+ /**
	1825	+ * Get the user's preferred date format.
	1826	+ * @return \string
	1827	+ */
	1828	+ function getDatePreference() {
	1829	+ // Important migration for old data rows
	1830	+ if ( is_null( $this->mDatePreference ) ) {
	1831	+ global $wgLang;
	1832	+ $value = $this->getOption( 'date' );
	1833	+ $map = $wgLang->getDatePreferenceMigrationMap();
	1834	+ if ( isset( $map[$value] ) ) {
	1835	+ $value = $map[$value];
	1836	+ }
	1837	+ $this->mDatePreference = $value;
	1838	+ }
	1839	+ return $this->mDatePreference;
	1840	+ }
	1841	+
	1842	+ /**
	1843	+ * Get the permissions this user has.
	1844	+ * @return \arrayof{\string}
	1845	+ */
1717	1846	function getRights() {
1718	1847	if ( is_null( $this->mRights ) ) {
1719	1848	$this->mRights = self::getGroupPermissions( $this->getEffectiveGroups() );
—	—	@@ -1726,7 +1855,7 @@
1727	1856	/**
1728	1857	* Get the list of explicit group memberships this user has.
1729	1858	* The implicit * and user groups are not included.
1730		~~- * @return array of strings~~
	1859	+ * @return \arrayof{\string}
1731	1860	*/
1732	1861	function getGroups() {
1733	1862	$this->load();
—	—	@@ -1737,8 +1866,8 @@
1738	1867	* Get the list of implicit group memberships this user has.
1739	1868	* This includes all explicit groups, plus 'user' if logged in,
1740	1869	* '*' for all accounts and autopromoted groups
1741		~~- * @param $recache Boolean: don't use the cache~~
1742		~~- * @return array of strings~~
	1870	+ * @param $recache \bool Whether to avoid the cache
	1871	+ * @return \arrayof{\string}
1743	1872	*/
1744	1873	function getEffectiveGroups( $recache = false ) {
1745	1874	if ( $recache \|\| is_null( $this->mEffectiveGroups ) ) {
—	—	@@ -1759,7 +1888,10 @@
1760	1889	return $this->mEffectiveGroups;
1761	1890	}
1762	1891
1763		~~- /* Return the edit count for the user. This is where User::edits should have been */~~
	1892	+ /**
	1893	+ * Get the user's edit count.
	1894	+ * @return \int
	1895	+ */
1764	1896	function getEditCount() {
1765	1897	if ($this->mId) {
1766	1898	if ( !isset( $this->mEditCount ) ) {
—	—	@@ -1776,7 +1908,7 @@
1777	1909	/**
1778	1910	* Add the user to the given group.
1779	1911	* This takes immediate effect.
1780		~~- * @param $group string~~
	1912	+ * @param $group \string Name of the group to add
1781	1913	*/
1782	1914	function addGroup( $group ) {
1783	1915	$dbw = wfGetDB( DB_MASTER );
—	—	@@ -1800,7 +1932,7 @@
1801	1933	/**
1802	1934	* Remove the user from the given group.
1803	1935	* This takes immediate effect.
1804		~~- * @param $group string~~
	1936	+ * @param $group \string Name of the group to remove
1805	1937	*/
1806	1938	function removeGroup( $group ) {
1807	1939	$this->load();
—	—	@@ -1821,27 +1953,24 @@
1822	1954
1823	1955
1824	1956	/**
1825		~~- * A more legible check for non-anonymousness.~~
1826		~~- * Returns true if the user is not an anonymous visitor.~~
1827		- *
1828		~~- * @return bool~~
	1957	+ * Get whether the user is logged in
	1958	+ * @return \bool
1829	1959	*/
1830	1960	function isLoggedIn() {
1831	1961	return $this->getID() != 0;
1832	1962	}
1833	1963
1834	1964	/**
1835		~~- * A more legible check for anonymousness.~~
1836		~~- * Returns true if the user is an anonymous visitor.~~
1837		- *
1838		~~- * @return bool~~
	1965	+ * Get whether the user is anonymous
	1966	+ * @return \bool
1839	1967	*/
1840	1968	function isAnon() {
1841	1969	return !$this->isLoggedIn();
1842	1970	}
1843	1971
1844	1972	/**
1845		~~- * Whether the user is a bot~~
	1973	+ * Get whether the user is a bot
	1974	+ * @return \bool
1846	1975	* @deprecated
1847	1976	*/
1848	1977	function isBot() {
—	—	@@ -1851,8 +1980,8 @@
1852	1981
1853	1982	/**
1854	1983	* Check if user is allowed to access a feature / make an action
1855		~~- * @param $action String: action to be checked~~
1856		~~- * @return boolean True: action is allowed, False: action should not be allowed~~
	1984	+ * @param $action \string action to be checked
	1985	+ * @return \bool True if action is allowed, else false
1857	1986	*/
1858	1987	function isAllowed($action='') {
1859	1988	if ( $action === '' )
—	—	@@ -1864,7 +1993,7 @@
1865	1994
1866	1995	/**
1867	1996	* Check whether to enable recent changes patrol features for this user
1868		~~- * @return bool~~
	1997	+ * @return \bool
1869	1998	*/
1870	1999	public function useRCPatrol() {
1871	2000	global $wgUseRCPatrol;
—	—	@@ -1872,8 +2001,8 @@
1873	2002	}
1874	2003
1875	2004	/**
1876		~~- * Check whether to enable recent changes patrol features for this user~~
1877		~~- * @return bool~~
	2005	+ * Check whether to enable new pages patrol features for this user
	2006	+ * @return \bool
1878	2007	*/
1879	2008	public function useNPPatrol() {
1880	2009	global $wgUseRCPatrol, $wgUseNPPatrol;
—	—	@@ -1881,7 +2010,8 @@
1882	2011	}
1883	2012
1884	2013	/**
1885		~~- * Load a skin if it doesn't exist or return it~~
	2014	+ * Get the current skin, loading it if required
	2015	+ * @return \type{Skin}
1886	2016	* @todo FIXME : need to check the old failback system [AV]
1887	2017	*/
1888	2018	function &getSkin() {
—	—	@@ -1899,13 +2029,10 @@
1900	2030	return $this->mSkin;
1901	2031	}
1902	2032
1903		~~- /**#@+~~
1904		~~- * @param $title Title: article title to look at~~
1905		~~- */~~
1906		-
1907	2033	/**
1908		~~- * Check watched status of an article~~
1909		~~- * @return bool True if article is watched~~
	2034	+ * Check the watched status of an article.
	2035	+ * @param $title \type{Title} Title of the article to look at
	2036	+ * @return \bool True if article is watched
1910	2037	*/
1911	2038	function isWatched( $title ) {
1912	2039	$wl = WatchedItem::fromUserTitle( $this, $title );
—	—	@@ -1913,7 +2040,8 @@
1914	2041	}
1915	2042
1916	2043	/**
1917		~~- * Watch an article~~
	2044	+ * Watch an article.
	2045	+ * @param $title \type{Title} Title of the article to look at
1918	2046	*/
1919	2047	function addWatch( $title ) {
1920	2048	$wl = WatchedItem::fromUserTitle( $this, $title );
—	—	@@ -1922,7 +2050,8 @@
1923	2051	}
1924	2052
1925	2053	/**
1926		~~- * Stop watching an article~~
	2054	+ * Stop watching an article.
	2055	+ * @param $title \type{Title} Title of the article to look at
1927	2056	*/
1928	2057	function removeWatch( $title ) {
1929	2058	$wl = WatchedItem::fromUserTitle( $this, $title );
—	—	@@ -1934,6 +2063,7 @@
1935	2064	* Clear the user's notification timestamp for the given title.
1936	2065	* If e-notif e-mails are on, they will receive notification mails on
1937	2066	* the next change of the page if it's watched etc.
	2067	+ * @param $title \type{Title} Title of the article to look at
1938	2068	*/
1939	2069	function clearNotification( &$title ) {
1940	2070	global $wgUser, $wgUseEnotif, $wgShowUpdatedMarker;
—	—	@@ -1989,14 +2119,12 @@
1990	2120	}
1991	2121	}
1992	2122
1993		~~- /*#@-/~~
1994		-
1995	2123	/**
1996	2124	* Resets all of the given user's page-change notification timestamps.
1997	2125	* If e-notif e-mails are on, they will receive notification mails on
1998	2126	* the next change of any watched page.
1999	2127	*
2000		~~- * @param $currentUser Int: user ID number~~
	2128	+ * @param $currentUser \int User ID
2001	2129	*/
2002	2130	function clearAllNotifications( $currentUser ) {
2003	2131	global $wgUseEnotif, $wgShowUpdatedMarker;
—	—	@@ -2019,8 +2147,9 @@
2020	2148	}
2021	2149
2022	2150	/**
	2151	+ * Encode this user's options as a string
	2152	+ * @return \string Encoded options
2023	2153	* @private
2024		~~- * @return string Encoding options~~
2025	2154	*/
2026	2155	function encodeOptions() {
2027	2156	$this->load();
—	—	@@ -2036,6 +2165,8 @@
2037	2166	}
2038	2167
2039	2168	/**
	2169	+ * Set this user's options from an encoded string
	2170	+ * @param $str \string Encoded options to import
2040	2171	* @private
2041	2172	*/
2042	2173	function decodeOptions( $str ) {
—	—	@@ -2049,6 +2180,13 @@
2050	2181	}
2051	2182	}
2052	2183
	2184	+ /**
	2185	+ * Set a cookie on the user's client
	2186	+ * @param $name \string Name of the cookie to set
	2187	+ * @param $name \string Value to set
	2188	+ * @param $name \int Expiration time, as a UNIX time value;
	2189	+ * if 0 or not specified, use the default $wgCookieExpiration
	2190	+ */
2053	2191	protected function setCookie( $name, $value, $exp=0 ) {
2054	2192	global $wgCookiePrefix,$wgCookieDomain,$wgCookieSecure,$wgCookieExpiration, $wgCookieHttpOnly;
2055	2193	if( $exp == 0 ) {
—	—	@@ -2085,10 +2223,17 @@
2086	2224	}
2087	2225	}
2088	2226
	2227	+ /**
	2228	+ * Clear a cookie on the user's client
	2229	+ * @param $name \string Name of the cookie to clear
	2230	+ */
2089	2231	protected function clearCookie( $name ) {
2090	2232	$this->setCookie( $name, '', time() - 86400 );
2091	2233	}
2092	2234
	2235	+ /**
	2236	+ * Set the default cookies for this session on the user's client.
	2237	+ */
2093	2238	function setCookies() {
2094	2239	$this->load();
2095	2240	if ( 0 == $this->mId ) return;
—	—	@@ -2119,7 +2264,7 @@
2120	2265	}
2121	2266
2122	2267	/**
2123		~~- * Logout user.~~
	2268	+ * Log this user out.
2124	2269	*/
2125	2270	function logout() {
2126	2271	global $wgUser;
—	—	@@ -2129,8 +2274,9 @@
2130	2275	}
2131	2276
2132	2277	/**
2133		~~- * Really logout user~~
2134		~~- * Clears the cookies and session, resets the instance cache~~
	2278	+ * Clear the user's cookies and session, and reset the instance cache.
	2279	+ * @private
	2280	+ * @see logout()
2135	2281	*/
2136	2282	function doLogout() {
2137	2283	$this->clearInstanceCache( 'defaults' );
—	—	@@ -2145,7 +2291,7 @@
2146	2292	}
2147	2293
2148	2294	/**
2149		~~- * Save object settings into database~~
	2295	+ * Save this user's settings into the database.
2150	2296	* @todo Only rarely do all these fields need to be set!
2151	2297	*/
2152	2298	function saveSettings() {
—	—	@@ -2179,7 +2325,7 @@
2180	2326	}
2181	2327
2182	2328	/**
2183		~~- * Checks if a user with the given name exists, returns the ID.~~
	2329	+ * If only this user's username is known, and it exists, return the user ID.
2184	2330	*/
2185	2331	function idForName() {
2186	2332	$s = trim( $this->getName() );
—	—	@@ -2196,18 +2342,18 @@
2197	2343	/**
2198	2344	* Add a user to the database, return the user object
2199	2345	*
2200		~~- * @param $name String: the user's name~~
2201		~~- * @param $params Associative array of non-default parameters to save to the database:~~
2202		~~- * password The user's password. Password logins will be disabled if this is omitted.~~
2203		~~- * newpassword A temporary password mailed to the user~~
2204		~~- * email The user's email address~~
2205		~~- * email_authenticated The email authentication timestamp~~
2206		~~- * real_name The user's real name~~
2207		~~- * options An associative array of non-default options~~
2208		~~- * token Random authentication token. Do not set.~~
2209		~~- * registration Registration timestamp. Do not set.~~
	2346	+ * @param $name \string Username to add
	2347	+ * @param $params \arrayof{\string} Non-default parameters to save to the database:
	2348	+ * - password The user's password. Password logins will be disabled if this is omitted.
	2349	+ * - newpassword A temporary password mailed to the user
	2350	+ * - email The user's email address
	2351	+ * - email_authenticated The email authentication timestamp
	2352	+ * - real_name The user's real name
	2353	+ * - options An associative array of non-default options
	2354	+ * - token Random authentication token. Do not set.
	2355	+ * - registration Registration timestamp. Do not set.
2210	2356	*
2211		~~- * @return User object, or null if the username already exists~~
	2357	+ * @return \type{User} A new User object, or null if the username already exists
2212	2358	*/
2213	2359	static function createNew( $name, $params = array() ) {
2214	2360	$user = new User;
—	—	@@ -2245,7 +2391,7 @@
2246	2392	}
2247	2393
2248	2394	/**
2249		~~- * Add an existing user object to the database~~
	2395	+ * Add this existing user object to the database
2250	2396	*/
2251	2397	function addToDatabase() {
2252	2398	$this->load();
—	—	@@ -2269,13 +2415,13 @@
2270	2416	);
2271	2417	$this->mId = $dbw->insertId();
2272	2418
2273		~~- # Clear instance cache other than user table data, which is already accurate~~
	2419	+ // Clear instance cache other than user table data, which is already accurate
2274	2420	$this->clearInstanceCache();
2275	2421	}
2276	2422
2277	2423	/**
2278		~~- * If the (non-anonymous) user is blocked, this function will block any IP address~~
2279		~~- * that they successfully log on from.~~
	2424	+ * If this (non-anonymous) user is blocked, block any IP address
	2425	+ * they've successfully logged in from.
2280	2426	*/
2281	2427	function spreadBlock() {
2282	2428	wfDebug( __METHOD__."()\n" );
—	—	@@ -2304,7 +2450,7 @@
2305	2451	* which will give them a chance to modify this key based on their own
2306	2452	* settings.
2307	2453	*
2308		~~- * @return string~~
	2454	+ * @return \string
2309	2455	*/
2310	2456	function getPageRenderingHash() {
2311	2457	global $wgContLang, $wgUseDynamicDates, $wgLang;
—	—	@@ -2337,21 +2483,28 @@
2338	2484	return $confstr;
2339	2485	}
2340	2486
	2487	+ /**
	2488	+ * Get whether the user is explicitly blocked from account creation.
	2489	+ * @return \bool
	2490	+ */
2341	2491	function isBlockedFromCreateAccount() {
2342	2492	$this->getBlockedStatus();
2343	2493	return $this->mBlock && $this->mBlock->mCreateAccount;
2344	2494	}
2345	2495
2346	2496	/**
2347		~~- * Determine if the user is blocked from using Special:Emailuser.~~
2348		- *
2349		~~- * @return boolean~~
	2497	+ * Get whether the user is blocked from using Special:Emailuser.
	2498	+ * @return \bool
2350	2499	*/
2351	2500	function isBlockedFromEmailuser() {
2352	2501	$this->getBlockedStatus();
2353	2502	return $this->mBlock && $this->mBlock->mBlockEmail;
2354	2503	}
2355	2504
	2505	+ /**
	2506	+ * Get whether the user is allowed to create an account.
	2507	+ * @return \bool
	2508	+ */
2356	2509	function isAllowedToCreateAccount() {
2357	2510	return $this->isAllowed( 'createaccount' ) && !$this->isBlockedFromCreateAccount();
2358	2511	}
—	—	@@ -2366,7 +2519,7 @@
2367	2520	/**
2368	2521	* Get this user's personal page title.
2369	2522	*
2370		~~- * @return Title~~
	2523	+ * @return \type{Title}
2371	2524	*/
2372	2525	function getUserPage() {
2373	2526	return Title::makeTitle( NS_USER, $this->getName() );
—	—	@@ -2375,7 +2528,7 @@
2376	2529	/**
2377	2530	* Get this user's talk page title.
2378	2531	*
2379		~~- * @return Title~~
	2532	+ * @return \type{Title}
2380	2533	*/
2381	2534	function getTalkPage() {
2382	2535	$title = $this->getUserPage();
—	—	@@ -2383,6 +2536,8 @@
2384	2537	}
2385	2538
2386	2539	/**
	2540	+ * Get the maximum valid user ID.
	2541	+ * @return \int
2387	2542	* @static
2388	2543	*/
2389	2544	function getMaxID() {
—	—	@@ -2399,7 +2554,7 @@
2400	2555	/**
2401	2556	* Determine whether the user is a newbie. Newbies are either
2402	2557	* anonymous IPs, or the most recently created accounts.
2403		~~- * @return bool True if it is a newbie.~~
	2558	+ * @return \bool True if the user is a newbie
2404	2559	*/
2405	2560	function isNewbie() {
2406	2561	return !$this->isAllowed( 'autoconfirmed' );
—	—	@@ -2409,7 +2564,7 @@
2410	2565	* Is the user active? We check to see if they've made at least
2411	2566	* X number of edits in the last Y days.
2412	2567	*
2413		~~- * @return bool true if the user is active, false if not~~
	2568	+ * @return \bool True if the user is active, false if not.
2414	2569	*/
2415	2570	public function isActiveEditor() {
2416	2571	global $wgActiveUserEditCount, $wgActiveUserDays;
—	—	@@ -2433,8 +2588,8 @@
2434	2589
2435	2590	/**
2436	2591	* Check to see if the given clear-text password is one of the accepted passwords
2437		~~- * @param $password String: user password.~~
2438		~~- * @return bool True if the given password is correct otherwise False.~~
	2592	+ * @param $password \string user password.
	2593	+ * @return \bool True if the given password is correct, otherwise False.
2439	2594	*/
2440	2595	function checkPassword( $password ) {
2441	2596	global $wgAuth;
—	—	@@ -2474,7 +2629,7 @@
2475	2630	/**
2476	2631	* Check if the given clear-text password matches the temporary password
2477	2632	* sent by e-mail for password reset operations.
2478		~~- * @return bool~~
	2633	+ * @return \bool
2479	2634	*/
2480	2635	function checkTemporaryPassword( $plaintext ) {
2481	2636	return self::comparePasswords( $this->mNewpassword, $plaintext, $this->getId() );
—	—	@@ -2486,9 +2641,8 @@
2487	2642	* login credentials aren't being hijacked with a foreign form
2488	2643	* submission.
2489	2644	*
2490		~~- * @param $salt Mixed: optional function-specific data for hash.~~
2491		~~- * Use a string or an array of strings.~~
2492		~~- * @return string~~
	2645	+ * @param $salt \2types{\string,\arrayof{\string}} Optional function-specific data for hashing
	2646	+ * @return \string The new edit token
2493	2647	*/
2494	2648	function editToken( $salt = '' ) {
2495	2649	if ( $this->isAnon() ) {
—	—	@@ -2508,9 +2662,10 @@
2509	2663	}
2510	2664
2511	2665	/**
2512		~~- * Generate a hex-y looking random token for various uses.~~
2513		~~- * Could be made more cryptographically sure if someone cares.~~
2514		~~- * @return string~~
	2666	+ * Generate a looking random token for various uses.
	2667	+ *
	2668	+ * @param $salt \string Optional salt value
	2669	+ * @return \string The new random token
2515	2670	*/
2516	2671	function generateToken( $salt = '' ) {
2517	2672	$token = dechex( mt_rand() ) . dechex( mt_rand() );
—	—	@@ -2523,9 +2678,9 @@
2524	2679	* user's own login session, not a form submission from a third-party
2525	2680	* site.
2526	2681	*
2527		~~- * @param $val String: the input value to compare~~
2528		~~- * @param $salt String: optional function-specific data for hash~~
2529		~~- * @return bool~~
	2682	+ * @param $val \string Input value to compare
	2683	+ * @param $salt \string Optional function-specific data for hashing
	2684	+ * @return \bool Whether the token matches
2530	2685	*/
2531	2686	function matchEditToken( $val, $salt = '' ) {
2532	2687	$sessionToken = $this->editToken( $salt );
—	—	@@ -2536,7 +2691,12 @@
2537	2692	}
2538	2693
2539	2694	/**
2540		~~- * Check whether the edit token is fine except for the suffix~~
	2695	+ * Check given value against the token value stored in the session,
	2696	+ * ignoring the suffix.
	2697	+ *
	2698	+ * @param $val \string Input value to compare
	2699	+ * @param $salt \string Optional function-specific data for hashing
	2700	+ * @return \bool Whether the token matches
2541	2701	*/
2542	2702	function matchEditTokenNoSuffix( $val, $salt = '' ) {
2543	2703	$sessionToken = $this->editToken( $salt );
—	—	@@ -2547,10 +2707,7 @@
2548	2708	* Generate a new e-mail confirmation token and send a confirmation/invalidation
2549	2709	* mail to the user's given address.
2550	2710	*
2551		~~- * Calls saveSettings() internally; as it has side effects, not committing changes~~
2552		~~- * would be pretty silly.~~
2553		- *
2554		~~- * @return mixed True on success, a WikiError object on failure.~~
	2711	+ * @return \2types{\bool,\type{WikiError}} True on success, a WikiError object on failure.
2555	2712	*/
2556	2713	function sendConfirmationMail() {
2557	2714	global $wgLang;
—	—	@@ -2573,11 +2730,11 @@
2574	2731	* Send an e-mail to this user's account. Does not check for
2575	2732	* confirmed status or validity.
2576	2733	*
2577		~~- * @param $subject string~~
2578		~~- * @param $body string~~
2579		~~- * @param $from string: optional from address; default $wgPasswordSender will be used otherwise.~~
2580		~~- * @param $replyto string~~
2581		~~- * @return mixed True on success, a WikiError object on failure.~~
	2734	+ * @param $subject \string Message subject
	2735	+ * @param $body \string Message body
	2736	+ * @param $from \string Optional From address; if unspecified, default $wgPasswordSender will be used
	2737	+ * @param $replyto \string
	2738	+ * @return \2types{\bool,\type{WikiError}} True on success, a WikiError object on failure
2582	2739	*/
2583	2740	function sendMail( $subject, $body, $from = null, $replyto = null ) {
2584	2741	if( is_null( $from ) ) {
—	—	@@ -2592,13 +2749,13 @@
2593	2750
2594	2751	/**
2595	2752	* Generate, store, and return a new e-mail confirmation code.
2596		~~- * A hash (unsalted since it's used as a key) is stored.~~
	2753	+ * A hash (unsalted, since it's used as a key) is stored.
2597	2754	*
2598		~~- * Call saveSettings() after calling this function to commit~~
	2755	+ * @note Call saveSettings() after calling this function to commit
2599	2756	* this change to the database.
2600	2757	*
2601		~~- * @param &$expiration mixed output: accepts the expiration time~~
2602		~~- * @return string~~
	2758	+ * @param[out] &$expiration \mixed Accepts the expiration time
	2759	+ * @return \string
2603	2760	* @private
2604	2761	*/
2605	2762	function confirmationToken( &$expiration ) {
—	—	@@ -2615,8 +2772,8 @@
2616	2773
2617	2774	/**
2618	2775	* Return a URL the user can use to confirm their email address.
2619		~~- * @param $token accepts the email confirmation token~~
2620		~~- * @return string~~
	2776	+ * @param $token \string Accepts the email confirmation token
	2777	+ * @return \string
2621	2778	* @private
2622	2779	*/
2623	2780	function confirmationTokenUrl( $token ) {
—	—	@@ -2624,8 +2781,8 @@
2625	2782	}
2626	2783	/**
2627	2784	* Return a URL the user can use to invalidate their email address.
2628		~~- * @param $token accepts the email confirmation token~~
2629		~~- * @return string~~
	2785	+ * @param $token \string Accepts the email confirmation token
	2786	+ * @return \string
2630	2787	* @private
2631	2788	*/
2632	2789	function invalidationTokenUrl( $token ) {
—	—	@@ -2637,10 +2794,14 @@
2638	2795	* This uses $wgArticlePath directly as a quickie hack to use the
2639	2796	* hardcoded English names of the Special: pages, for ASCII safety.
2640	2797	*
2641		~~- * Since these URLs get dropped directly into emails, using the~~
	2798	+ * @note Since these URLs get dropped directly into emails, using the
2642	2799	* short English names avoids insanely long URL-encoded links, which
2643	2800	* also sometimes can get corrupted in some browsers/mailers
2644	2801	* (bug 6957 with Gmail and Internet Explorer).
	2802	+ *
	2803	+ * @param $page \string Special page
	2804	+ * @param $token \string Token
	2805	+ * @return \string Formatted URL
2645	2806	*/
2646	2807	protected function getTokenUrl( $page, $token ) {
2647	2808	global $wgArticlePath;
—	—	@@ -2654,7 +2815,7 @@
2655	2816	/**
2656	2817	* Mark the e-mail address confirmed.
2657	2818	*
2658		~~- * Call saveSettings() after calling this function to commit the change.~~
	2819	+ * @note Call saveSettings() after calling this function to commit the change.
2659	2820	*/
2660	2821	function confirmEmail() {
2661	2822	$this->setEmailAuthenticationTimestamp( wfTimestampNow() );
—	—	@@ -2662,10 +2823,10 @@
2663	2824	}
2664	2825
2665	2826	/**
2666		~~- * Invalidate the user's email confirmation, unauthenticate the email~~
2667		~~- * if it was already confirmed.~~
	2827	+ * Invalidate the user's e-mail confirmation, and unauthenticate the e-mail
	2828	+ * address if it was already confirmed.
2668	2829	*
2669		~~- * Call saveSettings() after calling this function to commit the change.~~
	2830	+ * @note Call saveSettings() after calling this function to commit the change.
2670	2831	*/
2671	2832	function invalidateEmail() {
2672	2833	$this->load();
—	—	@@ -2675,6 +2836,10 @@
2676	2837	return true;
2677	2838	}
2678	2839
	2840	+ /**
	2841	+ * Set the e-mail authentication timestamp.
	2842	+ * @param $timestamp \string TS_MW timestamp
	2843	+ */
2679	2844	function setEmailAuthenticationTimestamp( $timestamp ) {
2680	2845	$this->load();
2681	2846	$this->mEmailAuthenticated = $timestamp;
—	—	@@ -2684,7 +2849,7 @@
2685	2850	/**
2686	2851	* Is this user allowed to send e-mails within limits of current
2687	2852	* site configuration?
2688		~~- * @return bool~~
	2853	+ * @return \bool
2689	2854	*/
2690	2855	function canSendEmail() {
2691	2856	$canSend = $this->isEmailConfirmed();
—	—	@@ -2695,7 +2860,7 @@
2696	2861	/**
2697	2862	* Is this user allowed to receive e-mails within limits of current
2698	2863	* site configuration?
2699		~~- * @return bool~~
	2864	+ * @return \bool
2700	2865	*/
2701	2866	function canReceiveEmail() {
2702	2867	return $this->isEmailConfirmed() && !$this->getOption( 'disablemail' );
—	—	@@ -2705,11 +2870,11 @@
2706	2871	* Is this user's e-mail address valid-looking and confirmed within
2707	2872	* limits of the current site configuration?
2708	2873	*
2709		~~- * If $wgEmailAuthentication is on, this may require the user to have~~
	2874	+ * @note If $wgEmailAuthentication is on, this may require the user to have
2710	2875	* confirmed their address by returning a code or using a password
2711	2876	* sent to the address from the wiki.
2712	2877	*
2713		~~- * @return bool~~
	2878	+ * @return \bool
2714	2879	*/
2715	2880	function isEmailConfirmed() {
2716	2881	global $wgEmailAuthentication;
—	—	@@ -2729,8 +2894,8 @@
2730	2895	}
2731	2896
2732	2897	/**
2733		~~- * Return true if there is an outstanding request for e-mail confirmation.~~
2734		~~- * @return bool~~
	2898	+ * Check whether there is an outstanding request for e-mail confirmation.
	2899	+ * @return \bool
2735	2900	*/
2736	2901	function isEmailConfirmationPending() {
2737	2902	global $wgEmailAuthentication;
—	—	@@ -2741,10 +2906,10 @@
2742	2907	}
2743	2908
2744	2909	/**
2745		~~- * Get the timestamp of account creation, or false for~~
2746		~~- * non-existent/anonymous user accounts~~
	2910	+ * Get the timestamp of account creation.
2747	2911	*
2748		~~- * @return mixed~~
	2912	+ * @return \2types{\string,\bool} string Timestamp of account creation, or false for
	2913	+ * non-existent/anonymous user accounts.
2749	2914	*/
2750	2915	public function getRegistration() {
2751	2916	return $this->mId > 0
—	—	@@ -2753,8 +2918,10 @@
2754	2919	}
2755	2920
2756	2921	/**
2757		~~- * @param $groups Array: list of groups~~
2758		~~- * @return array list of permission key names for given groups combined~~
	2922	+ * Get the permissions associated with a given list of groups
	2923	+ *
	2924	+ * @param $groups \arrayof{\string} List of internal group names
	2925	+ * @return \arrayof{\string} List of permission key names for given groups combined
2759	2926	*/
2760	2927	static function getGroupPermissions( $groups ) {
2761	2928	global $wgGroupPermissions;
—	—	@@ -2771,8 +2938,8 @@
2772	2939	/**
2773	2940	* Get all the groups who have a given permission
2774	2941	*
2775		~~- * @param $role String: Role to check~~
2776		~~- * @return array list of groups with the given permission~~
	2942	+ * @param $role \string Role to check
	2943	+ * @return \arrayof{\string} List of internal group names with the given permission
2777	2944	*/
2778	2945	static function getGroupsWithPermission( $role ) {
2779	2946	global $wgGroupPermissions;
—	—	@@ -2786,8 +2953,10 @@
2787	2954	}
2788	2955
2789	2956	/**
2790		~~- * @param $group String: key name~~
2791		~~- * @return string localized descriptive name for group, if provided~~
	2957	+ * Get the localized descriptive name for a group, if it exists
	2958	+ *
	2959	+ * @param $group \string Internal group name
	2960	+ * @return \string
2792	2961	*/
2793	2962	static function getGroupName( $group ) {
2794	2963	global $wgMessageCache;
—	—	@@ -2800,8 +2969,10 @@
2801	2970	}
2802	2971
2803	2972	/**
2804		~~- * @param $group String: key name~~
2805		~~- * @return string localized descriptive name for member of a group, if provided~~
	2973	+ * Get the localized descriptive name for a member of a group, if it exists
	2974	+ *
	2975	+ * @param $group \string Internal group name
	2976	+ * @return \string
2806	2977	*/
2807	2978	static function getGroupMember( $group ) {
2808	2979	global $wgMessageCache;
—	—	@@ -2816,9 +2987,8 @@
2817	2988	/**
2818	2989	* Return the set of defined explicit groups.
2819	2990	* The implicit groups (by default *, 'user' and 'autoconfirmed')
2820		~~- * are not included, as they are defined automatically,~~
2821		~~- * not in the database.~~
2822		~~- * @return array~~
	2991	+ * are not included, as they are defined automatically, not in the database.
	2992	+ * @return \arrayof{\string}
2823	2993	*/
2824	2994	static function getAllGroups() {
2825	2995	global $wgGroupPermissions;
—	—	@@ -2829,7 +2999,8 @@
2830	3000	}
2831	3001
2832	3002	/**
2833		~~- * Get a list of all available permissions~~
	3003	+ * Get a list of all available permissions.
	3004	+ * @return \arrayof{\string}
2834	3005	*/
2835	3006	static function getAllRights() {
2836	3007	if ( self::$mAllRights === false ) {
—	—	@@ -2846,8 +3017,7 @@
2847	3018
2848	3019	/**
2849	3020	* Get a list of implicit groups
2850		- *
2851		~~- * @return array~~
	3021	+ * @return \arrayof{\string}
2852	3022	*/
2853	3023	public static function getImplicitGroups() {
2854	3024	global $wgImplicitGroups;
—	—	@@ -2859,8 +3029,8 @@
2860	3030	/**
2861	3031	* Get the title of a page describing a particular group
2862	3032	*
2863		~~- * @param $group Name of the group~~
2864		~~- * @return mixed~~
	3033	+ * @param $group \string Internal group name
	3034	+ * @return \2types{\type{Title},\bool} Title of the page if it exists, false otherwise
2865	3035	*/
2866	3036	static function getGroupPage( $group ) {
2867	3037	global $wgMessageCache;
—	—	@@ -2875,11 +3045,12 @@
2876	3046	}
2877	3047
2878	3048	/**
2879		~~- * Create a link to the group in HTML, if available~~
	3049	+ * Create a link to the group in HTML, if available;
	3050	+ * else return the group name.
2880	3051	*
2881		~~- * @param $group Name of the group~~
2882		~~- * @param $text The text of the link~~
2883		~~- * @return mixed~~
	3052	+ * @param $group \string Internal name of the group
	3053	+ * @param $text \string The text of the link
	3054	+ * @return \string HTML link to the group
2884	3055	*/
2885	3056	static function makeGroupLinkHTML( $group, $text = '' ) {
2886	3057	if( $text == '' ) {
—	—	@@ -2896,11 +3067,12 @@
2897	3068	}
2898	3069
2899	3070	/**
2900		~~- * Create a link to the group in Wikitext, if available~~
	3071	+ * Create a link to the group in Wikitext, if available;
	3072	+ * else return the group name.
2901	3073	*
2902		~~- * @param $group Name of the group~~
2903		~~- * @param $text The text of the link (by default, the name of the group)~~
2904		~~- * @return mixed~~
	3074	+ * @param $group \string Internal name of the group
	3075	+ * @param $text \string The text of the link
	3076	+ * @return \string Wikilink to the group
2905	3077	*/
2906	3078	static function makeGroupLinkWiki( $group, $text = '' ) {
2907	3079	if( $text == '' ) {
—	—	@@ -2959,6 +3131,12 @@
2960	3132	$this->invalidateCache();
2961	3133	}
2962	3134
	3135	+ /**
	3136	+ * Get the description of a given right
	3137	+ *
	3138	+ * @param $right \string Right to query
	3139	+ * @return \string
	3140	+ */
2963	3141	static function getRightDescription( $right ) {
2964	3142	global $wgMessageCache;
2965	3143	$wgMessageCache->loadAllMessages();
—	—	@@ -2972,8 +3150,9 @@
2973	3151	/**
2974	3152	* Make an old-style password hash
2975	3153	*
2976		~~- * @param $password String: plain-text password~~
2977		~~- * @param $userId String: user ID~~
	3154	+ * @param $password \string Plain-text password
	3155	+ * @param $userId \string User ID
	3156	+ * @return \string Password hash
2978	3157	*/
2979	3158	static function oldCrypt( $password, $userId ) {
2980	3159	global $wgPasswordSalt;
—	—	@@ -2987,8 +3166,10 @@
2988	3167	/**
2989	3168	* Make a new-style password hash
2990	3169	*
2991		~~- * @param $password String: plain-text password~~
2992		~~- * @param $salt String: salt, may be random or the user ID. False to generate a salt.~~
	3170	+ * @param $password \string Plain-text password
	3171	+ * @param $salt \string Optional salt, may be random or the user ID.
	3172	+ * If unspecified or false, will generate one automatically
	3173	+ * @return \string Password hash
2993	3174	*/
2994	3175	static function crypt( $password, $salt = false ) {
2995	3176	global $wgPasswordSalt;
—	—	@@ -3007,9 +3188,10 @@
3008	3189	* Compare a password hash with a plain-text password. Requires the user
3009	3190	* ID if there's a chance that the hash is an old-style hash.
3010	3191	*
3011		~~- * @param $hash String: password hash~~
3012		~~- * @param $password String: plain-text password to compare~~
3013		~~- * @param $userId String: user ID for old-style password salt~~
	3192	+ * @param $hash \string Password hash
	3193	+ * @param $password \string Plain-text password to compare
	3194	+ * @param $userId \string User ID for old-style password salt
	3195	+ * @return \bool
3014	3196	*/
3015	3197	static function comparePasswords( $hash, $password, $userId = false ) {
3016	3198	$m = false;

Status & tagging log

15:29, 12 September 2011 Meno25 (talk | contribs) changed the status of r38622 [removed: ok added: old]