From 40fc84b3427b2d7a4a8ed672f4ad5061a3d25aa4 Mon Sep 17 00:00:00 2001
From: Carsten Brandt <mail@cebe.cc>
Date: Mon, 25 Nov 2013 20:29:35 +0100
Subject: [PATCH] cleanup & docs

---
 extensions/elasticsearch/ActiveQuery.php  |  3 +--
 extensions/elasticsearch/ActiveRecord.php |  1 -
 extensions/elasticsearch/Command.php      |  7 -------
 extensions/elasticsearch/Connection.php   |  3 ---
 extensions/elasticsearch/Query.php        | 32 ++++++++++++++++++++++++++++++-
 5 files changed, 32 insertions(+), 14 deletions(-)

diff --git a/extensions/elasticsearch/ActiveQuery.php b/extensions/elasticsearch/ActiveQuery.php
index 6ad12e4..3df9d8d 100644
--- a/extensions/elasticsearch/ActiveQuery.php
+++ b/extensions/elasticsearch/ActiveQuery.php
@@ -6,10 +6,9 @@
  */
 
 namespace yii\elasticsearch;
-use Guzzle\Http\Client;
+
 use yii\db\ActiveQueryInterface;
 use yii\db\ActiveQueryTrait;
-use yii\helpers\Json;
 
 /**
  * ActiveQuery represents a [[Query]] associated with an [[ActiveRecord]] class.
diff --git a/extensions/elasticsearch/ActiveRecord.php b/extensions/elasticsearch/ActiveRecord.php
index 293200d..c7d3d98 100644
--- a/extensions/elasticsearch/ActiveRecord.php
+++ b/extensions/elasticsearch/ActiveRecord.php
@@ -10,7 +10,6 @@ namespace yii\elasticsearch;
 use yii\base\InvalidCallException;
 use yii\base\InvalidConfigException;
 use yii\base\NotSupportedException;
-use yii\db\TableSchema;
 use yii\helpers\Inflector;
 use yii\helpers\Json;
 use yii\helpers\StringHelper;
diff --git a/extensions/elasticsearch/Command.php b/extensions/elasticsearch/Command.php
index 58ac15a..b93b2d4 100644
--- a/extensions/elasticsearch/Command.php
+++ b/extensions/elasticsearch/Command.php
@@ -7,16 +7,9 @@
 
 namespace yii\elasticsearch;
 
-
-use Guzzle\Http\Exception\ClientErrorResponseException;
 use yii\base\Component;
-use yii\db\Exception;
 use yii\helpers\Json;
 
-// camelCase vs. _
-// http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/common-options.html#_result_casing
-
-
 /**
  * The Command class implements the API for accessing the elasticsearch REST API.
  *
diff --git a/extensions/elasticsearch/Connection.php b/extensions/elasticsearch/Connection.php
index 2f67e42..6216dc7 100644
--- a/extensions/elasticsearch/Connection.php
+++ b/extensions/elasticsearch/Connection.php
@@ -7,13 +7,10 @@
 
 namespace yii\elasticsearch;
 
-
-use Guzzle\Http\Exception\ClientErrorResponseException;
 use Yii;
 use yii\base\Component;
 use yii\base\Exception;
 use yii\base\InvalidConfigException;
-use yii\helpers\Json;
 
 /**
  * elasticsearch Connection is used to connect to an elasticsearch cluster version 0.20 or higher
diff --git a/extensions/elasticsearch/Query.php b/extensions/elasticsearch/Query.php
index d4fcde6..2ba1876 100644
--- a/extensions/elasticsearch/Query.php
+++ b/extensions/elasticsearch/Query.php
@@ -14,7 +14,37 @@ use yii\db\QueryInterface;
 use yii\db\QueryTrait;
 
 /**
- * Class Query
+ * Query represents a query to the search API of elasticsearch.
+ *
+ * Query provides a set of methods to facilitate the specification of different parameters of the query.
+ * These methods can be chained together.
+ *
+ * By calling [[createCommand()]], we can get a [[Command]] instance which can be further
+ * used to perform/execute the DB query against a database.
+ *
+ * For example,
+ *
+ * ~~~
+ * $query = new Query;
+ * $query->fields('id, name')
+ *     ->from('myindex', 'users')
+ *     ->limit(10);
+ * // build and execute the query
+ * $command = $query->createCommand();
+ * $rows = $command->search(); // this way you get the raw output of elasticsearch.
+ * ~~~
+ *
+ * You would normally call `$query->search()` instead of creating a command as this method
+ * adds the `indexBy()` feature and also removes some inconsistencies from the response.
+ *
+ * Query also provides some methods to easier get some parts of the result only:
+ *
+ * - [[one()]]: returns a single record populated with the first row of data.
+ * - [[all()]]: returns all records based on the query results.
+ * - [[count()]]: returns the number of records.
+ * - [[scalar()]]: returns the value of the first column in the first row of the query result.
+ * - [[column()]]: returns the value of the first column in the query result.
+ * - [[exists()]]: returns a value indicating whether the query result has data or not.
  *
  * @author Carsten Brandt <mail@cebe.cc>
  * @since 2.0