phpdocs

git-svn-id: http://dev.piwik.org/svn/trunk@2962 59fd770c-687e-43c8-a1e3-f5a4ff64c105

4 files changed, 69 insertions, 16 deletions

diff --git a/core/Auth.php b/core/Auth.php
index fa3b9d9e03..cd73f8a4d6 100644
--- a/core/Auth.php
+++ b/core/Auth.php
@@ -25,6 +25,8 @@ interface Piwik_Auth {
 	public function getName();
 
 	/**
+	 * Authenticates user
+	 *
 	 * @return Piwik_Auth_Result
 	 */
 	public function authenticate();
diff --git a/plugins/Login/Auth.php b/plugins/Login/Auth.php
index a20bb760d6..9c2e08b5d1 100644
--- a/plugins/Login/Auth.php
+++ b/plugins/Login/Auth.php
@@ -19,11 +19,21 @@ class Piwik_Login_Auth implements Piwik_Auth
 	protected $login = null;
 	protected $token_auth = null;
 
+	/**
+	 * Authentication module's name, e.g., "Login"
+	 *
+	 * @return string
+	 */
 	public function getName()
 	{
 		return 'Login';
 	}
 
+	/**
+	 * Authenticates user
+	 *
+	 * @return Piwik_Auth_Result
+	 */
 	public function authenticate()
 	{
 		$rootLogin = Zend_Registry::get('config')->superuser->login;
@@ -77,16 +87,33 @@ class Piwik_Login_Auth implements Piwik_Auth
 		return new Piwik_Auth_Result( Piwik_Auth_Result::FAILURE, $this->login, $this->token_auth );
 	}
 
+	/**
+	 * Accessor to set login name
+	 *
+	 * @param string $login user login
+	 */
 	public function setLogin($login)
 	{
 		$this->login = $login;
 	}
 
+	/**
+	 * Accessor to set authentication token
+	 *
+	 * @param string $token_auth authentication token
+	 */
 	public function setTokenAuth($token_auth)
 	{
 		$this->token_auth = $token_auth;
 	}
 
+	/**
+	 * Accessor to compute the hashed authentication token
+	 *
+	 * @param string $login user login
+	 * @param string $token_auth authentication token
+	 * @return string hashed authentication token
+	 */
 	public function getHashTokenAuth($login, $token_auth)
 	{
 		return md5($login . $token_auth);
diff --git a/plugins/Login/Controller.php b/plugins/Login/Controller.php
index 0f219bef4b..2ffccdc31f 100644
--- a/plugins/Login/Controller.php
+++ b/plugins/Login/Controller.php
@@ -97,11 +97,11 @@ class Piwik_Login_Controller extends Piwik_Controller
 	/**
 	 * Authenticate user and password.  Redirect if successful.
 	 *
-	 * @param string $login (user name)
-	 * @param string $md5Password (md5 hash of password)
+	 * @param string $login user name
+	 * @param string $md5Password md5 hash of password
 	 * @param bool $rememberMe Remember me?
-	 * @param string $urlToRedirect (URL to redirect to, if successfully authenticated)
-	 * @return string (failure message if unable to authenticate)
+	 * @param string $urlToRedirect URL to redirect to, if successfully authenticated
+	 * @return string failure message if unable to authenticate
 	 */
 	protected function authenticateAndRedirect($login, $md5Password, $rememberMe, $urlToRedirect = 'index.php')
 	{
@@ -140,8 +140,8 @@ class Piwik_Login_Controller extends Piwik_Controller
 	/**
 	 * Validate user (by username or email address).
 	 *
-	 * @param string $loginMail (user name or email address)
-	 * @return string (failure message if unable to validate)
+	 * @param string $loginMail user name or email address
+	 * @return string failure message if unable to validate
 	 */
 	protected function lostPasswordFormValidated($loginMail)
 	{
@@ -221,10 +221,10 @@ class Piwik_Login_Controller extends Piwik_Controller
 	/**
 	 * Validate password reset request.  If successful, set new password and redirect.
 	 *
-	 * @param string $loginMail (user name or email address)
-	 * @param string $token (password reset token)
-	 * @param string $pssword (new password)
-	 * @return string (failure message)
+	 * @param string $loginMail user name or email address
+	 * @param string $token password reset token
+	 * @param string $password new password
+	 * @return string failure message
 	 */
 	protected function resetPasswordFormValidated($loginMail, $token, $password)
 	{
@@ -270,7 +270,7 @@ class Piwik_Login_Controller extends Piwik_Controller
 	/**
 	 * Get user information
 	 *
-	 * @param string $loginMail (user login or email address)
+	 * @param string $loginMail user login or email address
 	 * @return array ("login" => '...', "email" => '...', "password" => '...') or null, if user not found
 	 */
 	protected function getUserInformation($loginMail)
@@ -302,9 +302,9 @@ class Piwik_Login_Controller extends Piwik_Controller
 	/**
 	 * Generate a password reset token.  Expires in (roughly) 24 hours.
 	 *
-	 * @param array (user information)
-	 * @param int $timestamp (Unix timestamp)
-	 * @return string (generated token)
+	 * @param array user information
+	 * @param int $timestamp Unix timestamp
+	 * @return string generated token
 	 */
 	protected function generatePasswordResetToken($user, $timestamp = null)
 	{
@@ -326,8 +326,8 @@ class Piwik_Login_Controller extends Piwik_Controller
 	 * Validate token.
 	 *
 	 * @param string $token
-	 * @param array $user (user information)
-	 * @return bool (true if valid, false otherwise)
+	 * @param array $user user information
+	 * @return bool true if valid, false otherwise
 	 */
 	protected function isValidToken($token, $user)
 	{
diff --git a/plugins/Login/Login.php b/plugins/Login/Login.php
index fac3dadc30..4b81297f81 100644
--- a/plugins/Login/Login.php
+++ b/plugins/Login/Login.php
@@ -38,6 +38,12 @@ class Piwik_Login extends Piwik_Plugin
 		return $hooks;
 	}
 
+	/**
+	 * Redirects to Login form with error message.
+	 * Listens to FrontController.NoAccessException hook.
+	 *
+	 * @param Piwik_Event_Notification $notification
+	 */
 	function noAccess( $notification )
 	{
 		$exception  = $notification->getNotificationObject();
@@ -47,6 +53,12 @@ class Piwik_Login extends Piwik_Plugin
 		$controller->login($exceptionMessage);
 	}
 
+	/**
+	 * Set login name and autehntication token for authentication request.
+	 * Listens to API.Request.authenticate hook.
+	 *
+	 * @param Piwik_Event_Notification $notification
+	 */
 	function ApiRequestAuthenticate($notification)
 	{
 		$tokenAuth = $notification->getNotificationObject();
@@ -54,6 +66,12 @@ class Piwik_Login extends Piwik_Plugin
 		Zend_Registry::get('auth')->setTokenAuth($tokenAuth);
 	}
 
+	/**
+	 * Initializes the authentication object.
+	 * Listens to FrontController.initAuthenticationObject hook.
+	 *
+	 * @param Piwik_Event_Notification $notification
+	 */
 	function initAuthenticationObject($notification)
 	{
 		$auth = new Piwik_Login_Auth();
@@ -81,6 +99,12 @@ class Piwik_Login extends Piwik_Plugin
 		$auth->setTokenAuth($defaultTokenAuth);
 	}
 	
+	/**
+	 * Authenticate user and initializes the session.
+	 * Listens to Login.initSession hook.
+	 *
+	 * @param Piwik_Event_Notification $notification
+	 */
 	function initSession($notification)
 	{
 		$info = $notification->getNotificationObject();