From f6784c6093bbd4bb91d953c882bbba7ed99cd5e9 Mon Sep 17 00:00:00 2001
From: andrewblond <andrewblond@yandex.com>
Date: Wed, 29 Oct 2014 17:44:03 +0300
Subject: [PATCH] Updated README files

---
 README.md    | 55 +++++++++++++++++++++++++++++++++++++++++++++++-----
 README.ru.md | 45 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 95 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 9d421a1b..cc3de336 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@ bem-naming
 About
 -----
 
-This tool allows getting information about BEM-entity using [string](#string-representation) as well as forming string representation based on [BEM-naming](#bem-naming).
+This tool allows getting information about BEM entity using [string](#string-representation) as well as forming string representation based on [BEM-naming](#bem-naming).
 
 String representation
 ---------------------
@@ -47,10 +47,55 @@ BEM-naming
 
 BEM-entities can be defined with a help of js-object with the following fields:
 
-* `block` — block's name. The field is required because block is the only independent BEM-entity.
-* `elem` — element's name.
-* `modName` — modifier's name.
-* `modVal` — modifier's value.
+* `block` — a block name. The field is required because only a block exists as an independent BEM entity
+* `elem` — an element name.
+* `modName` — a modifier name.
+* `modVal` — a modifier value.
+
+The modifier consists of a pair of fields `modName` and `modVal`. This means that the field `modVal` without `modName` has no meaning.
+
+Example:
+
+```js
+// The block modifier
+{
+    block: 'block',
+    modName: 'mod',
+    modVal: 'val'
+}
+
+// Not valid BEM-notation
+{
+    block: 'block',
+    modVal: 'val'
+}
+```
+
+To describe the boolean modifier field `modVal` must be specified as `true`.
+
+Example:
+
+```js
+// Boolean modifier of a block
+{
+    block: 'block',
+    modName: 'mod',
+    modVal: true
+}
+
+// Shorthand for the boolean modifier of a block
+{
+    block: 'block',
+    modName: 'mod'
+}
+
+// Not valid BEM-notation
+{
+    block: 'block',
+    modName: 'mod',
+    modVal: false
+}
+```
 
 API
 ---
diff --git a/README.ru.md b/README.ru.md
index 2b308aba..a9e476d3 100644
--- a/README.ru.md
+++ b/README.ru.md
@@ -52,6 +52,51 @@ bem-naming
 * `modName` — название модификатора.
 * `modVal` — значение модификатора.
 
+Модификатор состоит из пары `modName` и `modVal`. Это означает, что поле `modVal` без `modName` не имеет никакого смысла.
+
+Пример:
+
+```js
+// Модификатор блока
+{
+    block: 'block',
+    modName: 'mod',
+    modVal: 'val'
+}
+
+// Невалидная БЭМ-нотация
+{
+    block: 'block',
+    modVal: 'val'
+}
+```
+
+Чтобы задать булевый модификатор поле modVal должно быть указано со значением `true`. В таком случае отображаться будет только имя модификатора.
+
+Пример:
+
+```js
+// Булевый модификатор блока
+{
+    block: 'block',
+    modName: 'mod',
+    modVal: true
+}
+
+// Сокращенная запись булевого модификатора блока
+{
+    block: 'block',
+    modName: 'mod'
+}
+
+// Невалидная БЭМ-нотация
+{
+    block: 'block',
+    modName: 'mod',
+    modVal: false
+}
+```
+
 API
 ---