From cf523a4b4b328382fdd0955b403372871e93f647 Mon Sep 17 00:00:00 2001
From: fps01 <fps.06@mail.ru>
Date: Sat, 16 Jul 2016 15:19:21 +0300
Subject: [PATCH] documentation (Close #2) [skip ci]

---
 CHANCHELOG.md     | 16 ++++++++++++++++
 README.md         | 25 ++++++++++++++++++++++++-
 docs/ru/README.md | 42 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 82 insertions(+), 1 deletion(-)
 create mode 100644 CHANCHELOG.md
 create mode 100644 docs/ru/README.md

diff --git a/CHANCHELOG.md b/CHANCHELOG.md
new file mode 100644
index 0000000..89afe58
--- /dev/null
+++ b/CHANCHELOG.md
@@ -0,0 +1,16 @@
+Yii2 Mappable ActiveRecord Change Log
+=====================================
+
+1.1.0 under development
+-----------------------
+
+1.0.1 July 26, 2016
+-------------------
+
+- New #2: Added a russian documentation (fps01)
+- Enh #2: Fixed an english documentation (fps01)
+
+1.0.0 March 20, 2016
+--------------------
+
+- Initial release
\ No newline at end of file
diff --git a/README.md b/README.md
index f3738c6..1d58074 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,26 @@
-# Yii2 mappable ActiveRecord
+Yii2 mappable ActiveRecord
+==========================
 
 It is an extension for Yii framework 2 that gives an ability to use identity map for any ActiveRecord model.
 
 [![Build Status](https://travis-ci.org/yiister/yii2-mappable-ar.svg?branch=master)](https://travis-ci.org/yiister/yii2-mappable-ar)
 [![codecov.io](https://codecov.io/github/yiister/yii2-mappable-ar/coverage.svg?branch=master)](https://codecov.io/github/yiister/yii2-mappable-ar?branch=master)
 
+
+[Russian documentation](docs/ru).
+
+How it works
+------------
+
+`ActiveRecordTrait` overrides a `find` method of model. This method creates a custom `ActiveQuery`. When `one` (`all`) method is called, a got model (models) save to `identityMap` as array of attributes (It saves a memory). The next requests return data without queries to data base.
+
+By the way the next methods are allowed:
+
+- `getById(integer $id, boolean $asArray = false)` - get a model or an array of attributes (It depends on second param value) by primary key;
+- `getByAttribute(string $attribute, string $value, boolean $asArray = false)` - get a model or an array of attributes (It depends on second param value) by unique attribute value; 
+- `getMap()` - get all models from `identityMap` as array of attributes;
+- `clearMap()` - clear an `identityMap`.
+
 Installation
 ------------
 
@@ -34,3 +50,10 @@ use yiister\mappable\ActiveRecordTrait;
 ```
 
 to your model. After you may use `getById` and `getByAttribute` methods to get a model or an array.
+
+Using
+-----
+
+Just add `use yiister\mappable\ActiveRecordTrait;` to your model for using an identityMap. You got all features after it.
+
+**Warn!** Trait does not work if you override a `find` method in your model. This problem has a issue #7 on github.
\ No newline at end of file
diff --git a/docs/ru/README.md b/docs/ru/README.md
new file mode 100644
index 0000000..e37fd49
--- /dev/null
+++ b/docs/ru/README.md
@@ -0,0 +1,42 @@
+Yii2 mappable ActiveRecord
+==========================
+
+Это расширение для Yii framework 2 которое дает возможность использовать паттерн `IdentityMap` для любой модели `ActiveRecord`.
+
+Как это работает
+----------------
+
+`ActiveRecordTrait` переопределяет метод `find` модели. Этот метод создает свой собственный `ActiveQuery`. В последствии при вызове метода `one` (`all`) полученная модель (модели) сохраняются в `identityMap` в виде массива атрибутов (это экономит память). При последующих запросах, данные возвращаются без обращения к базе данных.
+
+Кроме этого, доступны следующие методы:
+
+- `getById(integer $id, boolean $asArray = false)` - получить модель или массив атрибутов (зависит от значения второго параметра) по первичному ключу;
+- `getByAttribute(string $attribute, string $value, boolean $asArray = false)` - получить модель или массив атрибутов (зависит от значения второго параметра) по значению уникального атрибута; 
+- `getMap()` - получить все полученные модели из `identityMap` в виде массива атрибутов;
+- `clearMap()` - очистить `identityMap`.
+
+Установка
+---------
+
+Предпочтительным вариантом установки является [composer](http://getcomposer.org/download/).
+
+Просто выполните команду
+
+```
+composer require --prefer-dist yiister/yii2-mappable-ar
+```
+
+или добавьте
+
+```json
+"yiister/yii2-mappable-ar": "~1.0.0"
+```
+
+в секцию `require` вашего файла composer.json.
+
+Использование
+-------------
+
+Для использования расширения достаточно указать для модели `use yiister\mappable\ActiveRecordTrait;`. После этого вам станут доступны все описанные возможности.
+
+**Важно!** Если у вас переопределен метод `find`, то треит работать не будет. По этому поводу есть задача #7 на github.