From: Antoine Musso <hashar@users.mediawiki.org>
Date: Sat, 4 Sep 2004 13:06:25 +0000 (+0000)
Subject: Phpdoc comments
X-Git-Tag: 1.5.0alpha1~2108
X-Git-Url: https://git.cyclocoop.org/%7B%24www_url%7Dadmin/compta/banques/?a=commitdiff_plain;h=bb69541c7795c0adbfd9427b44d8b038593f04a0;p=lhc%2Fweb%2Fwiklou.git

Phpdoc comments
---

diff --git a/includes/User.php b/includes/User.php
index 620b19d084..5f746e47c2 100644
--- a/includes/User.php
+++ b/includes/User.php
@@ -15,16 +15,21 @@ require_once( 'WatchedItem.php' );
  * @package MediaWiki
  */
 class User {
-	/* private */ var $mId, $mName, $mPassword, $mEmail, $mNewtalk;
-	/* private */ var $mRights, $mOptions;
-	/* private */ var $mDataLoaded, $mNewpassword;
-	/* private */ var $mSkin;
-	/* private */ var $mBlockedby, $mBlockreason;
-	/* private */ var $mTouched;
-	/* private */ var $mCookiePassword;
-	/* private */ var $mRealName;
-	/* private */ var $mHash;
-
+	/**#@+
+	 * @access private
+	 */
+	var $mId, $mName, $mPassword, $mEmail, $mNewtalk;
+	var $mRights, $mOptions;
+	var $mDataLoaded, $mNewpassword;
+	var $mSkin;
+	var $mBlockedby, $mBlockreason;
+	var $mTouched;
+	var $mCookiePassword;
+	var $mRealName;
+	var $mHash;
+	/**#@-*/
+
+	/** Construct using User:loadDefaults() */
 	function User()	{
 		$this->loadDefaults();
 	}
@@ -32,6 +37,7 @@ class User {
 	/**
 	 * Static factory method
 	 * @static
+	 * @param string $name Username, validated by Title:newFromText()
 	 */
 	function newFromName( $name ) {
 		$u = new User();
@@ -44,6 +50,9 @@ class User {
 	}
 
 	/**
+	 * Get username given an id.
+	 * @param integer $id Database user id
+	 * @return string Nickname of a user
 	 * @static
 	 */
 	function whoIs( $id )	{
@@ -52,6 +61,9 @@ class User {
 	}
 
 	/**
+	 * Get real username given an id.
+	 * @param integer $id Database user id
+	 * @return string Realname of a user
 	 * @static
 	 */
 	function whoIsReal( $id )	{
@@ -60,6 +72,9 @@ class User {
 	}
 
 	/**
+	 * Get database id given a user name
+	 * @param string $name Nickname of a user
+	 * @return integer|null Database user id (null: if non existent
 	 * @static
 	 */
 	function idFromName( $name ) {
@@ -82,6 +97,7 @@ class User {
 
 	/**
 	 * does the string match an anonymous user IP address?
+	 * @param string $name Nickname of a user
 	 * @static
 	 */
 	function isIP( $name ) {
@@ -89,7 +105,10 @@ class User {
 	}
 
 	/**
-	 * static
+	 * probably return a random password
+	 * @return string probably a random password
+	 * @static
+	 * @todo Check what is doing really [AV]
 	 */
 	function randomPassword() {
 		$pwchars = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz';
@@ -103,7 +122,8 @@ class User {
 	}
 
 	/**
-	 *
+	 * Set properties to default
+	 * Used at construction.
 	 */
 	function loadDefaults() {
 		global $wgLang, $wgIP;
@@ -130,6 +150,7 @@ class User {
 	}
 
 	/**
+	 * Get blocking information
 	 * @access private
 	 */
 	function getBlockedStatus() {
@@ -166,22 +187,37 @@ class User {
 		}
 	}
 
+	/**
+	 * Check if user is blocked
+	 * @return bool True if blocked, false otherwise
+	 */
 	function isBlocked() {
 		$this->getBlockedStatus();
 		if ( 0 === $this->mBlockedby ) { return false; }
 		return true;
 	}
-
+	
+	/**
+	 * Get name of blocker
+	 * @return string name of blocker
+	 */
 	function blockedBy() {
 		$this->getBlockedStatus();
 		return $this->mBlockedby;
 	}
-
+	
+	/**
+	 * Get blocking reason
+	 * @return string Blocking reason
+	 */
 	function blockedFor() {
 		$this->getBlockedStatus();
 		return $this->mBlockreason;
 	}
 
+	/**
+	 * Initialise php session
+	 */
 	function SetupSession() {
 		global $wgSessionsInMemcached, $wgCookiePath, $wgCookieDomain;
 		if( $wgSessionsInMemcached ) {
@@ -197,6 +233,7 @@ class User {
 	}
 
 	/**
+	 * Read datas from session
 	 * @static
 	 */
 	function loadFromSession() {
@@ -258,7 +295,7 @@ class User {
 	}
 
 	/**
-	 *
+	 * Load a user from the database
 	 */
 	function loadFromDatabase() {
 		global $wgCommandLineMode;
@@ -360,6 +397,12 @@ class User {
 		return ($timestamp >= $this->mTouched);
 	}
 
+	/**
+	 * Salt a password.
+	 * Will only be salted if $wgPasswordSalt is true
+	 * @param string Password.
+	 * @return string Salted password or clear password.
+	 */
 	function addSalt( $p ) {
 		global $wgPasswordSalt;
 		if($wgPasswordSalt)
@@ -368,6 +411,12 @@ class User {
 			return $p;
 	}
 
+	/**
+	 * Encrypt a password.
+	 * It can eventuall salt a password @see User::addSalt()
+	 * @param string $p clear Password.
+	 * @param string Encrypted password.
+	 */
 	function encryptPassword( $p ) {
 		return $this->addSalt( md5( $p ) );
 	}
@@ -460,6 +509,9 @@ class User {
 		return in_array( 'bureaucrat', $this->mRights );
 	}
 
+	/**
+	 * Wheter user is a bot
+	 */
 	function isBot() {
 		$this->loadFromDatabase();
 
@@ -521,26 +573,41 @@ class User {
 		return $this->mSkin;
 	}
 
+	/**#@+
+	 * @param string $title Article title to look at
+	 */
+	
+	/**
+	 * Check watched status of an article
+	 * @return bool Wheter article is watched
+	 */
 	function isWatched( $title ) {
 		$wl = WatchedItem::fromUserTitle( $this, $title );
 		return $wl->isWatched();
 	}
 
+	/**
+	 * Watch an article
+	 */
 	function addWatch( $title ) {
 		$wl = WatchedItem::fromUserTitle( $this, $title );
 		$wl->addWatch();
 		$this->invalidateCache();
 	}
 
+	/**
+	 * Stop watching an article
+	 */
 	function removeWatch( $title ) {
 		$wl = WatchedItem::fromUserTitle( $this, $title );
 		$wl->removeWatch();
 		$this->invalidateCache();
 	}
-
+	/**#@-*/
 
 	/**
 	 * @access private
+	 * @return string Encoding options
 	 */
 	function encodeOptions() {
 		$a = array();
@@ -583,6 +650,10 @@ class User {
 		}
 	}
 
+	/**
+	 * Logout user
+	 * It will clean the session cookie
+	 */
 	function logout() {
 		global $wgCookiePath, $wgCookieDomain, $wgDBname;
 		$this->mId = 0;
@@ -593,6 +664,9 @@ class User {
 		setcookie( $wgDBname.'Password', '', time() - 3600, $wgCookiePath, $wgCookieDomain );
 	}
 
+	/**
+	 * Save object settings into database
+	 */
 	function saveSettings() {
 		global $wgMemc, $wgDBname;
 		$fname = 'User::saveSettings';
@@ -645,6 +719,9 @@ class User {
 		return $id;
 	}
 
+	/**
+	 * Add user object to the database
+	 */
 	function addToDatabase() {
 		$fname = 'User::addToDatabase';
 		$dbw =& wfGetDB( DB_MASTER );
@@ -768,12 +845,19 @@ class User {
 		return $dbr->selectField( 'user', 'max(user_id)', false );
 	}
 
+	/**
+	 * Wheter the user is newbie
+	 * @document how are defined newbies.
+	 * @return bool True if it is a newbie.
+	 */
 	function isNewbie() {
 		return $this->mId > User::getMaxID() * 0.99 && !$this->isSysop() && !$this->isBot() || $this->getID() == 0;
 	}
 
 	/**
 	 * Check to see if the given clear-text password is one of the accepted passwords
+	 * @param string $password User password.
+	 * @return bool True if the given password is correct otherwise False.
 	 */
 	function checkPassword( $password ) {
 		$this->loadFromDatabase();