From 124f4fa9f769e96760d492aa92ef327b9a2b1c90 Mon Sep 17 00:00:00 2001
From: Paul Klimov <klimov.paul@gmail.com>
Date: Wed, 25 Dec 2013 13:33:34 +0200
Subject: [PATCH] Doc comments in "authclient" extension updated.

---
 extensions/yii/authclient/ClientInterface.php |  2 +-
 extensions/yii/authclient/OAuth1.php          |  2 +-
 extensions/yii/authclient/OpenId.php          | 32 ++++++++++++++++++++++++++-
 3 files changed, 33 insertions(+), 3 deletions(-)

diff --git a/extensions/yii/authclient/ClientInterface.php b/extensions/yii/authclient/ClientInterface.php
index bd76e3b..c9ea0f6 100644
--- a/extensions/yii/authclient/ClientInterface.php
+++ b/extensions/yii/authclient/ClientInterface.php
@@ -8,7 +8,7 @@
 namespace yii\authclient;
 
 /**
- * Class ProviderInterface
+ * ClientInterface declares basic interface all Auth clients should follow.
  *
  * @author Paul Klimov <klimov.paul@gmail.com>
  * @since 2.0
diff --git a/extensions/yii/authclient/OAuth1.php b/extensions/yii/authclient/OAuth1.php
index 3eaf82f..35bb74c 100644
--- a/extensions/yii/authclient/OAuth1.php
+++ b/extensions/yii/authclient/OAuth1.php
@@ -21,7 +21,7 @@ use Yii;
  * $oauthClient = new OAuth1();
  * $requestToken = $oauthClient->fetchRequestToken(); // Get request token
  * $url = $oauthClient->buildAuthUrl($requestToken); // Get authorization URL
- * Yii::$app->getResponse()->redirect($url); // Redirect to authorization URL
+ * return Yii::$app->getResponse()->redirect($url); // Redirect to authorization URL
  * // After user returns at our site:
  * $accessToken = $oauthClient->fetchAccessToken($requestToken); // Upgrade to access token
  * ~~~
diff --git a/extensions/yii/authclient/OpenId.php b/extensions/yii/authclient/OpenId.php
index 35527e9..6cd84f3 100644
--- a/extensions/yii/authclient/OpenId.php
+++ b/extensions/yii/authclient/OpenId.php
@@ -12,7 +12,27 @@ use yii\base\NotSupportedException;
 use Yii;
 
 /**
- * Class Client
+ * OpenId provides a simple interface for OpenID (1.1 and 2.0) authentication.
+ * Supports Yadis and HTML discovery.
+ *
+ * Usage:
+ *
+ * ~~~
+ * use yii\authclient\OpenId;
+ *
+ * $client = new OpenId();
+ * $client->authUrl = 'https://open.id.provider.url'; // Setup provider endpoint
+ * $url = $client->buildAuthUrl(); // Get authentication URL
+ * return Yii::$app->getResponse()->redirect($url); // Redirect to authentication URL
+ * // After user returns at our site:
+ * if ($client->validate()) { // validate response
+ *     $userAttributes = $client->getUserAttributes(); // get account info
+ *     ...
+ * }
+ * ~~~
+ *
+ * AX and SREG extensions are supported.
+ * To use them, specify [[requiredAttributes]] and/or [[optionalAttributes]].
  *
  * @see http://openid.net/
  *
@@ -32,10 +52,20 @@ class OpenId extends BaseClient implements ClientInterface
 	public $authUrl;
 	/**
 	 * @var array list of attributes, which always should be returned from server.
+	 * Attribute names should be always specified in AX format.
+	 * For example:
+	 * ~~~
+	 * ['namePerson/friendly', 'contact/email']
+	 * ~~~
 	 */
 	public $requiredAttributes = [];
 	/**
 	 * @var array list of attributes, which could be returned from server.
+	 * Attribute names should be always specified in AX format.
+	 * For example:
+	 * ~~~
+	 * ['namePerson/first', 'namePerson/last']
+	 * ~~~
 	 */
 	public $optionalAttributes = [];