Finishing touches on User.php documentation
authorFran Rogers <krimpet@users.mediawiki.org>
Thu, 7 Aug 2008 08:22:37 +0000 (08:22 +0000)
committerFran Rogers <krimpet@users.mediawiki.org>
Thu, 7 Aug 2008 08:22:37 +0000 (08:22 +0000)
includes/User.php
maintenance/Doxyfile

index b59b3a3..d0129c9 100644 (file)
@@ -461,8 +461,13 @@ class User {
         * addresses like this, if we allowed accounts like this to be created
         * new users could get the old edits of these anonymous users.
         *
+<<<<<<< .mine
+        * @param $name \type{\string} String to match
+        * @return \type{\bool} True or false
+=======
         * @param $name \type{\string}
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        static function isIP( $name ) {
                return preg_match('/^\d{1,3}\.\d{1,3}\.\d{1,3}\.(?:xxx|\d{1,3})$/',$name) || IP::isIPv6($name);
@@ -476,8 +481,13 @@ class User {
         * is longer than the maximum allowed username size or doesn't begin with
         * a capital letter.
         *
+<<<<<<< .mine
+        * @param $name \type{\string} String to match
+        * @return \type{\bool} True or false
+=======
         * @param $name \type{\string}
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        static function isValidUserName( $name ) {
                global $wgContLang, $wgMaxNameChars;
@@ -530,8 +540,13 @@ class User {
         * If an account already exists in this form, login will be blocked
         * by a failure to pass this function.
         *
+<<<<<<< .mine
+        * @param $name \type{\string} String to match
+        * @return \type{\bool} True or false
+=======
         * @param $name \type{\string}
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        static function isUsableName( $name ) {
                global $wgReservedUsernames;
@@ -562,8 +577,13 @@ class User {
         * rather than in isValidUserName() to avoid disrupting
         * existing accounts.
         *
+<<<<<<< .mine
+        * @param $name \type{\string} String to match
+        * @return \type{\bool} True or false
+=======
         * @param $name \type{\string}
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        static function isCreatableName( $name ) {
                return
@@ -576,8 +596,13 @@ class User {
        /**
         * Is the input a valid password for this user?
         *
+<<<<<<< .mine
+        * @param $password \type{\string} Desired password
+        * @return \type{\bool} True or false
+=======
         * @param $password \type{\string} Desired password
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function isValidPassword( $password ) {
                global $wgMinimalPasswordLength, $wgContLang;
@@ -602,8 +627,13 @@ class User {
         *
         * @todo Check for RFC 2822 compilance (bug 959)
         *
+<<<<<<< .mine
+        * @param $addr \type{\string} E-mail address
+        * @return \type{\bool} True or false
+=======
         * @param $addr \type{\string} E-mail address
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        public static function isValidEmailAddr( $addr ) {
                $result = null;
@@ -711,7 +741,11 @@ class User {
         * Return a random password. Sourced from mt_rand, so it's not particularly secure.
         * @todo hash random numbers to improve security, like generateToken()
         *
+<<<<<<< .mine
+        * @return \type{\string} New random password
+=======
         * @return \type{\string}
+>>>>>>> .r38752
         */
        static function randomPassword() {
                global $wgMinimalPasswordLength;
@@ -972,8 +1006,13 @@ class User {
        /**
         * Get a given default option value.
         *
+<<<<<<< .mine
+        * @param $opt \type{\string} Name of option to retrieve
+        * @return \type{\string} Default option value
+=======
         * @param $opt \type{\string} Name of option to retrieve
         * @return \type{\string}
+>>>>>>> .r38752
         */
        public static function getDefaultOption( $opt ) {
                $defOpts = self::getDefaultOptions();
@@ -986,7 +1025,7 @@ class User {
 
        /**
         * Get a list of user toggle names
-        * @return \arrayof{\string}
+        * @return \arrayof{\string} Array of user toggle names
         */
        static function getToggles() {
                global $wgContLang;
@@ -1073,8 +1112,13 @@ class User {
        /**
         * Whether the given IP is in the SORBS blacklist.
         *
+<<<<<<< .mine
+        * @param $ip \type{\string} IP to check
+        * @return \type{\bool} True if blacklisted
+=======
         * @param $ip \type{\string} IP to check
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function inSorbsBlacklist( $ip ) {
                global $wgEnableSorbs, $wgSorbsUrl;
@@ -1086,9 +1130,15 @@ class User {
        /**
         * Whether the given IP is in a given DNS blacklist.
         *
+<<<<<<< .mine
+        * @param $ip \type{\string} IP to check
+        * @param $base \type{\string} URL of the DNS blacklist
+        * @return \type{\bool} True if blacklisted
+=======
         * @param $ip \type{\string} IP to check
         * @param $base \type{\string} URL of the DNS blacklist
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function inDnsBlacklist( $ip, $base ) {
                wfProfileIn( __METHOD__ );
@@ -1122,7 +1172,11 @@ class User {
        /**
         * Is this user subject to rate limiting?
         *
+<<<<<<< .mine
+        * @return \type{\bool} True if rate limited
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        public function isPingLimitable() {
                global $wgRateLimitsExcludedGroups;
@@ -1311,7 +1365,11 @@ class User {
 
        /**
         * Get the user name, or the IP of an anonymous user
+<<<<<<< .mine
+        * @return \type{\string} User's name or IP address
+=======
         * @return \type{\string}
+>>>>>>> .r38752
         */
        function getName() {
                if ( !$this->mDataLoaded && $this->mFrom == 'name' ) {
@@ -1347,7 +1405,11 @@ class User {
 
        /**
         * Get the user's name escaped by underscores.
+<<<<<<< .mine
+        * @return \type{\string} Username escaped by underscores
+=======
         * @return \type{\string}
+>>>>>>> .r38752
         */
        function getTitleKey() {
                return str_replace( ' ', '_', $this->getName() );
@@ -1617,7 +1679,11 @@ class User {
        
        /**
         * Get the user's current token.
+<<<<<<< .mine
+        * @return \type{\string} Token
+=======
         * @return \type{\string}
+>>>>>>> .r38752
         */
        function getToken() {
                $this->load();
@@ -1676,7 +1742,11 @@ class User {
        /**
         * Has password reminder email been sent within the last 
         * $wgPasswordReminderResendTime hours?
+<<<<<<< .mine
+        * @return \type{\bool} True or false
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function isPasswordReminderThrottled() {
                global $wgPasswordReminderResendTime;
@@ -1690,7 +1760,11 @@ class User {
 
        /**
         * Get the user's e-mail address
+<<<<<<< .mine
+        * @return \type{\string} User's -mail address
+=======
         * @return \type{\string}
+>>>>>>> .r38752
         */
        function getEmail() {
                $this->load();
@@ -1720,7 +1794,11 @@ class User {
 
        /**
         * Get the user's real name
+<<<<<<< .mine
+        * @return \type{\string} User's real name
+=======
         * @return \type{\string}
+>>>>>>> .r38752
         */
        function getRealName() {
                $this->load();
@@ -1822,7 +1900,11 @@ class User {
 
        /**
         * Get the user's preferred date format.
+<<<<<<< .mine
+        * @return \type{\string} User's preferred date format
+=======
         * @return \type{\string}
+>>>>>>> .r38752
         */
        function getDatePreference() {
                // Important migration for old data rows
@@ -1840,7 +1922,7 @@ class User {
 
        /**
         * Get the permissions this user has.
-        * @return \arrayof{\string}
+        * @return \arrayof{\string} Array of permission names
         */
        function getRights() {
                if ( is_null( $this->mRights ) ) {
@@ -1855,7 +1937,7 @@ class User {
        /**
         * Get the list of explicit group memberships this user has.
         * The implicit * and user groups are not included.
-        * @return \arrayof{\string}
+        * @return \arrayof{\string} Array of internal group names
         */
        function getGroups() {
                $this->load();
@@ -1866,8 +1948,13 @@ class User {
         * Get the list of implicit group memberships this user has.
         * This includes all explicit groups, plus 'user' if logged in,
         * '*' for all accounts and autopromoted groups
+<<<<<<< .mine
+        * @param $recache \type{\bool} Whether to avoid the cache
+        * @return \arrayof{\string} Array of internal group names
+=======
         * @param $recache \type{\bool} Whether to avoid the cache
         * @return \arrayof{\string}
+>>>>>>> .r38752
         */
        function getEffectiveGroups( $recache = false ) {
                if ( $recache || is_null( $this->mEffectiveGroups ) ) {
@@ -1890,7 +1977,11 @@ class User {
 
        /**
         * Get the user's edit count.
+<<<<<<< .mine
+        * @return \type{\int} User's edit count
+=======
         * @return \type{\int}
+>>>>>>> .r38752
         */
        function getEditCount() {
                if ($this->mId) {
@@ -1954,7 +2045,11 @@ class User {
 
        /**
         * Get whether the user is logged in
+<<<<<<< .mine
+        * @return \type{\bool} True or false
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function isLoggedIn() {
                return $this->getID() != 0;
@@ -1962,7 +2057,11 @@ class User {
 
        /**
         * Get whether the user is anonymous
+<<<<<<< .mine
+        * @return \type{\bool} True or false
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function isAnon() {
                return !$this->isLoggedIn();
@@ -1970,7 +2069,11 @@ class User {
 
        /**
         * Get whether the user is a bot
+<<<<<<< .mine
+        * @return \type{\bool} True or false
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         * @deprecated
         */
        function isBot() {
@@ -1993,7 +2096,11 @@ class User {
 
        /**
        * Check whether to enable recent changes patrol features for this user
+<<<<<<< .mine
+       * @return \type{\bool} True or false
+=======
        * @return \type{\bool}
+>>>>>>> .r38752
        */
        public function useRCPatrol() {
                global $wgUseRCPatrol;
@@ -2002,7 +2109,11 @@ class User {
 
        /**
        * Check whether to enable new pages patrol features for this user
+<<<<<<< .mine
+       * @return \type{\bool} True or false
+=======
        * @return \type{\bool}
+>>>>>>> .r38752
        */
        public function useNPPatrol() {
                global $wgUseRCPatrol, $wgUseNPPatrol;
@@ -2011,7 +2122,7 @@ class User {
 
        /**
         * Get the current skin, loading it if required
-        * @return \type{Skin}
+        * @return \type{Skin} Current skin
         * @todo FIXME : need to check the old failback system [AV]
         */
        function &getSkin() {
@@ -2450,7 +2561,11 @@ class User {
         * which will give them a chance to modify this key based on their own
         * settings.
         *
+<<<<<<< .mine
+        * @return \type{\string} Page rendering hash
+=======
         * @return \type{\string}
+>>>>>>> .r38752
         */
        function getPageRenderingHash() {
                global $wgContLang, $wgUseDynamicDates, $wgLang;
@@ -2485,7 +2600,11 @@ class User {
 
        /**
         * Get whether the user is explicitly blocked from account creation.
+<<<<<<< .mine
+        * @return \type{\bool} True if blocked
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function isBlockedFromCreateAccount() {
                $this->getBlockedStatus();
@@ -2494,7 +2613,11 @@ class User {
 
        /**
         * Get whether the user is blocked from using Special:Emailuser.
+<<<<<<< .mine
+        * @return \type{\bool} True if blocked
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function isBlockedFromEmailuser() {
                $this->getBlockedStatus();
@@ -2503,7 +2626,11 @@ class User {
 
        /**
         * Get whether the user is allowed to create an account.
+<<<<<<< .mine
+        * @return \type{\bool} True if allowed
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function isAllowedToCreateAccount() {
                return $this->isAllowed( 'createaccount' ) && !$this->isBlockedFromCreateAccount();
@@ -2519,7 +2646,7 @@ class User {
        /**
         * Get this user's personal page title.
         *
-        * @return \type{Title}
+        * @return \type{Title} User's personal page title
         */
        function getUserPage() {
                return Title::makeTitle( NS_USER, $this->getName() );
@@ -2528,7 +2655,7 @@ class User {
        /**
         * Get this user's talk page title.
         *
-        * @return \type{Title}
+        * @return \type{Title} User's talk page title
         */
        function getTalkPage() {
                $title = $this->getUserPage();
@@ -2537,7 +2664,11 @@ class User {
 
        /**
         * Get the maximum valid user ID.
+<<<<<<< .mine
+        * @return \type{\int} %User ID
+=======
         * @return \type{\int}
+>>>>>>> .r38752
         * @static
         */
        function getMaxID() {
@@ -2629,7 +2760,11 @@ class User {
        /**
         * Check if the given clear-text password matches the temporary password
         * sent by e-mail for password reset operations.
+<<<<<<< .mine
+        * @return \type{\bool} True if matches, false otherwise
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function checkTemporaryPassword( $plaintext ) {
                return self::comparePasswords( $this->mNewpassword, $plaintext, $this->getId() );
@@ -2730,11 +2865,19 @@ class User {
         * Send an e-mail to this user's account. Does not check for
         * confirmed status or validity.
         *
+<<<<<<< .mine
+        * @param $subject \type{\string} Message subject
+        * @param $body \type{\string} Message body
+        * @param $from \type{\string} Optional From address; if unspecified, default $wgPasswordSender will be used
+        * @param $replyto \type{\string} Reply-to address
+        * @return \twotypes{\bool,WikiError} True on success, a WikiError object on failure
+=======
         * @param $subject \type{\string} Message subject
         * @param $body \type{\string} Message body
         * @param $from \type{\string} Optional From address; if unspecified, default $wgPasswordSender will be used
         * @param $replyto \type{\string}
         * @return \twotypes{\bool,WikiError} True on success, a WikiError object on failure
+>>>>>>> .r38752
         */
        function sendMail( $subject, $body, $from = null, $replyto = null ) {
                if( is_null( $from ) ) {
@@ -2754,8 +2897,13 @@ class User {
         * @note Call saveSettings() after calling this function to commit
         * this change to the database.
         *
+<<<<<<< .mine
+        * @param[out] &$expiration \type{\mixed} Accepts the expiration time
+        * @return \type{\string} New token
+=======
         * @param[out] &$expiration \type{\mixed} Accepts the expiration time
         * @return \type{\string}
+>>>>>>> .r38752
         * @private
         */
        function confirmationToken( &$expiration ) {
@@ -2772,8 +2920,13 @@ class User {
 
        /**
        * Return a URL the user can use to confirm their email address.
+<<<<<<< .mine
+        * @param $token \type{\string} Accepts the email confirmation token
+        * @return \type{\string} New token URL
+=======
         * @param $token \type{\string} Accepts the email confirmation token
         * @return \type{\string}
+>>>>>>> .r38752
         * @private
         */
        function confirmationTokenUrl( $token ) {
@@ -2781,8 +2934,13 @@ class User {
        }
        /**
         * Return a URL the user can use to invalidate their email address.
+<<<<<<< .mine
+        * @param $token \type{\string} Accepts the email confirmation token
+        * @return \type{\string} New token URL
+=======
         * @param $token \type{\string} Accepts the email confirmation token
         * @return \type{\string}
+>>>>>>> .r38752
         * @private
         */
        function invalidationTokenUrl( $token ) {
@@ -2849,7 +3007,11 @@ class User {
        /**
         * Is this user allowed to send e-mails within limits of current
         * site configuration?
+<<<<<<< .mine
+        * @return \type{\bool} True if allowed
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function canSendEmail() {
                $canSend = $this->isEmailConfirmed();
@@ -2860,7 +3022,11 @@ class User {
        /**
         * Is this user allowed to receive e-mails within limits of current
         * site configuration?
+<<<<<<< .mine
+        * @return \type{\bool} True if allowed
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function canReceiveEmail() {
                return $this->isEmailConfirmed() && !$this->getOption( 'disablemail' );
@@ -2874,7 +3040,11 @@ class User {
         * confirmed their address by returning a code or using a password
         * sent to the address from the wiki.
         *
+<<<<<<< .mine
+        * @return \type{\bool} True if conffirmed
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function isEmailConfirmed() {
                global $wgEmailAuthentication;
@@ -2895,7 +3065,11 @@ class User {
 
        /**
         * Check whether there is an outstanding request for e-mail confirmation.
+<<<<<<< .mine
+        * @return \type{\bool} True if pending
+=======
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        function isEmailConfirmationPending() {
                global $wgEmailAuthentication;
@@ -2955,8 +3129,13 @@ class User {
        /**
         * Get the localized descriptive name for a group, if it exists
         *
+<<<<<<< .mine
+        * @param $group \type{\string} Internal group name
+        * @return \type{\string} Localized descriptive group name
+=======
         * @param $group \type{\string} Internal group name
         * @return \type{\string}
+>>>>>>> .r38752
         */
        static function getGroupName( $group ) {
                global $wgMessageCache;
@@ -2971,8 +3150,13 @@ class User {
        /**
         * Get the localized descriptive name for a member of a group, if it exists
         *
+<<<<<<< .mine
+        * @param $group \type{\string} Internal group name
+        * @return \type{\string} Localized name for group member
+=======
         * @param $group \type{\string} Internal group name
         * @return \type{\string}
+>>>>>>> .r38752
         */
        static function getGroupMember( $group ) {
                global $wgMessageCache;
@@ -2988,7 +3172,7 @@ class User {
         * Return the set of defined explicit groups.
         * The implicit groups (by default *, 'user' and 'autoconfirmed')
         * are not included, as they are defined automatically, not in the database.
-        * @return \arrayof{\string}
+        * @return \arrayof{\string} Array of internal group names
         */
        static function getAllGroups() {
                global $wgGroupPermissions;
@@ -3000,7 +3184,7 @@ class User {
 
        /**
         * Get a list of all available permissions.
-        * @return \arrayof{\string}
+        * @return \arrayof{\string} Array of permission names
         */
        static function getAllRights() {
                if ( self::$mAllRights === false ) {
@@ -3017,7 +3201,7 @@ class User {
 
        /**
         * Get a list of implicit groups
-        * @return \arrayof{\string}
+        * @return \arrayof{\string} Array of internal group names
         */
        public static function getImplicitGroups() {
                global $wgImplicitGroups;
@@ -3134,8 +3318,13 @@ class User {
        /**
         * Get the description of a given right
         *
+<<<<<<< .mine
+        * @param $right \type{\string} Right to query
+        * @return \type{\string} Localized description of the right
+=======
         * @param $right \type{\string} Right to query
         * @return \type{\string}
+>>>>>>> .r38752
         */
        static function getRightDescription( $right ) {
                global $wgMessageCache;
@@ -3188,10 +3377,17 @@ class User {
         * Compare a password hash with a plain-text password. Requires the user
         * ID if there's a chance that the hash is an old-style hash.
         *
+<<<<<<< .mine
+        * @param $hash \type{\string} Password hash
+        * @param $password \type{\string} Plain-text password to compare
+        * @param $userId \type{\string} %User ID for old-style password salt
+        * @return \type{\bool} True if matches, false otherwise
+=======
         * @param $hash \type{\string} Password hash
         * @param $password \type{\string} Plain-text password to compare
         * @param $userId \type{\string} %User ID for old-style password salt
         * @return \type{\bool}
+>>>>>>> .r38752
         */
        static function comparePasswords( $hash, $password, $userId = false ) {
                $m = false;
index 6931f4a..e1df2be 100644 (file)
@@ -16,7 +16,7 @@
 PROJECT_NAME           = MediaWiki
 PROJECT_NUMBER         = {{CURRENT_VERSION}}
 OUTPUT_DIRECTORY       = {{OUTPUT_DIRECTORY}}
-CREATE_SUBDIRS         = NO
+CREATE_SUBDIRS         = YES
 OUTPUT_LANGUAGE        = English
 BRIEF_MEMBER_DESC      = YES
 REPEAT_BRIEF           = YES
@@ -175,7 +175,7 @@ CHM_FILE               =
 HHC_LOCATION           = 
 GENERATE_CHI           = NO
 BINARY_TOC             = NO
-TOC_EXPAND             = NO
+TOC_EXPAND             = YES
 DISABLE_INDEX          = NO
 ENUM_VALUES_PER_LINE   = 4
 GENERATE_TREEVIEW      = YES
@@ -191,8 +191,8 @@ COMPACT_LATEX          = NO
 PAPER_TYPE             = a4wide
 EXTRA_PACKAGES         = 
 LATEX_HEADER           = 
-PDF_HYPERLINKS         = NO
-USE_PDFLATEX           = NO
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
 LATEX_BATCHMODE        = NO
 LATEX_HIDE_INDICES     = NO
 #---------------------------------------------------------------------------
@@ -207,7 +207,7 @@ RTF_EXTENSIONS_FILE    =
 #---------------------------------------------------------------------------
 # configuration options related to the man page output
 #---------------------------------------------------------------------------
-GENERATE_MAN           = YES
+GENERATE_MAN           = NO
 MAN_OUTPUT             = man
 MAN_EXTENSION          = .3
 MAN_LINKS              = NO