Doc cleanup (#1468)

bem · Dec 24, 2016 · 4134205 · 4134205
1 parent cfb1332
commit 4134205
Show file tree

Hide file tree

Showing 26 changed files with 567 additions and 423 deletions.
diff --git a/common.blocks/clearfix/clearfix.ru.md b/common.blocks/clearfix/clearfix.ru.md
@@ -34,7 +34,6 @@
 }]
 ```
 
-
 Примешивание к блоку-контейнеру:
 
 ```bemjson
@@ -66,8 +65,7 @@
 }]
 ```
 
-
-### Публичные технологии блока
+## Публичные технологии блока
 
 Блок реализован в технологиях:
 

diff --git a/common.blocks/cookie/cookie.ru.md b/common.blocks/cookie/cookie.ru.md
@@ -1,15 +1,15 @@
 # cookie
 
-Блок предоставляет объект, содержащий набор методов для работы с куки браузера (JS-свойство `document.cookie`).
+Блок предоставляет объект, содержащий набор методов для работы с cookie браузера (JS-свойство `document.cookie`).
 
 ## Обзор
 
 ### Свойства и методы объекта
 
-| Имя | Возвращаемое значение | Описание |
+| Имя | Тип возвращаемого значения | Описание |
 | -------- | --- | -------- |
-| <a href="#fields-get">get</a>(<code>{String} name</code>) | <code>{String}</code>&#124;<code>{null}</code> | Cлужит для получения значения, хранящегося в куки браузера. |
-| <a href="#fields-set">set</a>(<code>{String} name</code>, <br><code>{String} val</code>, <br><code>[{Object} options]</code>) | <code>{String}</code> | Cлужит для записи куки с заданным именем.|
+| <a href="#fields-get">get</a>(`name`) | `String` &#124; `null` | Служит для получения значения, хранящегося в cookie браузера. |
+| <a href="#fields-set">set</a>(`name`, `val`, `[options]`) | `String` | Cлужит для записи cookie с заданным именем.|
 
 ### Публичные технологии блока
 
@@ -20,61 +20,73 @@
 ## Описание
 
 <a name="fields"></a>
+
 ### Свойства и методы объекта
 
 <a name="fields-get"></a>
+
 #### Метод `get`
 
-Метод служит для получения значения, хранящегося в куки, для имени переданного аргументом.
+Метод служит для получения значения, хранящегося в cookie, для имени переданного аргументом.
+
+**Принимаемые аргументы:**
 
-Принимаемые аргументы:
+| Аргумент | Тип | Описание |
+| ------- | --- | -------- |
+| `name`&#42; | `String` | Имя cookie. |
 
-* `name` `{String}` – имя куки. Обязательный аргумент.
+&#42; Обязательный аргумент.
 
-Возвращаемое значение:
+**Возвращает:**
 
-* `{String}` в случае если куки с заданным именем было установлено. Значение автоматически декодируется с помощью [decodeURIComponent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent).
-* `null` если куки с заданным именем отсутствует.
+* `String` — если cookie с заданным именем было установлено. Значение автоматически декодируется с помощью [decodeURIComponent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent).
+* `null` — если cookie с заданным именем отсутствует.
+
+Пример:
 
 ```js
 modules.require('cookie', function(cookie) {
 
-cookie.set('mycookie', 'foobar');
-console.log(cookie.get('mycookie')); // 'foobar'
-console.log(cookie.get('foo')); // null
-    
+    cookie.set('mycookie', 'foobar');
+    console.log(cookie.get('mycookie')); // 'foobar'
+    console.log(cookie.get('foo')); // null
+
 });
 ```
 
 <a name="fields-set"></a>
+
 #### Метод `set`
 
-Метод служит для записи куки с заданным именем. Помимо имени и значения, методу можно передать хеш с дополнительными параметрами куки.
+Метод служит для записи cookie с заданным именем. Помимо имени и значения, методу можно передать хеш с дополнительными параметрами cookie.
+
+**Принимаемые аргументы:**
+
+| Аргумент | Тип | Описание |
+| ------- | --- | -------- |
+| `name`&#42; | `String` | Имя cookie. |
+| `val`&#42; | `String` &#124; `null` | Значение cookie. При установке в качестве значения `null` cookie удаляется.|
+| [`options`] | `Object` | Опции. </br></br> Свойства объекта: </br></br> &#8226; `expires` (`Number`) – срок жизни cookie в сутках. При отрицательном значении cookie будет удалено. Альтернативно, можно передать в качестве значения сформированный объект даты (`new Date()`). </br> &#8226; `path` (`String`) – путь от корня домена внутри которого будет доступно cookie. </br> &#8226; `domain` (`String`) – домен. По умолчанию текущий домен. </br> &#8226; `secure` (`Boolean`) – флаг, указывающий на необходимость использования с cookie шифрованного соединения SSL. По умолчанию `false`. |
 
-Принимаемые аргументы:
+&#42; Обязательный аргумент.
 
-* `name` `{String}` – имя куки. Обязательный аргумент.
-* `val` `{String}` | `{null}` – строка со значением, ассоциируемым с именем. При установке в качестве значения `null` куки будет удалено. Обязательный аргумент.
-* [`options` `{Object}`] – хеш с дополнительными параметрами. В хеше допустимы следующие свойства:
-    * `expires` `{Number}` – срок жизни куки в сутках. При отрицательном значении куки будет удалено. Альтернативно, можно передать в качестве значения сформированный объект даты (`new Date()`).
-    * `path` `{String}` – путь от корня домена внутри которого будет доступно куки.
-    * `domain` `{String}` – домен в явном виде. По умолчанию – текущий.
-    * `secure` `{Boolean}` – логический флаг, указывающий на необходимость принудительного использования с куки шифрованного соединения SSL. По умолчанию `false`.
+**Возвращает:** объект `this`.
 
-Возвращает объект `this`.
+Пример:
 
 ```js
 modules.require('cookie', function(cookie) {
 
-cookie.set('mycookie', 'foobar', {
-    expires : 1, // срок жизни одни сутки
-    path : '/', // доступно для всех страниц домена
-    secure : true // передавать куки только по SSL
-});
-console.log(cookie.get('mycookie')); // 'foobar'
+    cookie.set('mycookie', 'foobar', {
+        expires : 1, // срок жизни одни сутки
+        path : '/', // доступно для всех страниц
+        secure : true // передавать cookie только по SSL
+    });
+
+    console.log(cookie.get('mycookie')); // 'foobar'
 
-cookie.set('mycookie', null }); // удаляем куки
-console.log(cookie.get('mycookie')); // null
+    cookie.set('mycookie', null }); // удаляем cookie
+    console.log(cookie.get('mycookie')); // null
 
 });
 ```
diff --git a/common.blocks/dom/dom.ru.md b/common.blocks/dom/dom.ru.md
@@ -1,18 +1,18 @@
 # dom
 
-Блок предоставляет объект, содержащий набор методов для работы с DOM-деревом. 
+Блок предоставляет объект, содержащий набор методов для работы с DOM-деревом.
 
 ## Обзор
 
 ### Свойства и методы объекта
 
-| Имя | Возвращаемое значение | Описание |
+| Имя | Тип возвращаемого значения | Описание |
 | -------- | --- | -------- |
-| <a href="#fields-contains">contains</a>(<br><code>{jQuery} ctx</code>,<br><code>{jQuery} domElem</code>) | <code>{Boolean}</code> | Проверяет, содержит ли один DOM-элемент другой. |
-| <a href="#fields-getFocused">getFocused</a>(<br><code>{jQuery} domElem</code>) | <code>{jQuery}</code> | Служит для получения ссылки на DOM-элемент в фокусе. |
-| <a href="#fields-containsFocus">containsFocus</a>(<br><code>{jQuery} domElem</code>) | <code>{Boolean}</code> | Проверят, содержит ли DOM-элемент или его потомки фокус. |
-| <a href="#fields-isFocusable">isFocusable</a>(<br><code>{jQuery} domElem</code>) | <code>{Boolean}</code> | Проверят, может ли DOM-элемент находиться в фокусе. |
-| <a href="#fields-isEditable">isEditable</a>(<br><code>{jQuery} domElem</code>) | <code>{Boolean}</code> | Проверят, возможен ли в DOM-элементе ввод текста. |
+| <a href="#fields-contains">contains</a>(<br>`ctx {jQuery}`,<br>`domElem {jQuery}`) | `Boolean` | Проверяет, содержит ли один DOM-элемент другой. |
+| <a href="#fields-getFocused">getFocused</a>(<br>`domElem {jQuery} `) | `jQuery` | Служит для получения ссылки на DOM-элемент в фокусе. |
+| <a href="#fields-containsFocus">containsFocus</a>(<br>`domElem {jQuery} `) | `Boolean` | Проверят, содержит ли DOM-элемент или его потомки фокус. |
+| <a href="#fields-isFocusable">isFocusable</a>(<br>`domElem {jQuery} `) | `Boolean` | Проверят, может ли DOM-элемент находиться в фокусе. |
+| <a href="#fields-isEditable">isEditable</a>(<br>`domElem {jQuery}`) | `Boolean` | Проверят, возможен ли в DOM-элементе ввод текста. |
 
 ### Публичные технологии блока
 
@@ -23,19 +23,23 @@
 ## Описание
 
 <a name="fields"></a>
+
 ### Свойства и методы объекта
 
 <a name="fields-contains"></a>
+
 #### Метод `contains`
 
 Метод позволяет проверить содержит ли некоторый DOM-элемент `ctx` элемент `domElem`.
 
-Принимаемые аргументы: 
+**Принимаемые аргументы:**
 
- * `ctx` `{jQuery}` – DOM-элемент внутри которого производится поиск. Обязательный аргумент.
- * `domElem` `{jQuery}` – искомый DOM-элемент. Обязательный аргумент.
+* `ctx {jQuery}` – DOM-элемент внутри которого производится поиск. Обязательный аргумент.
+* `domElem {jQuery}` – искомый DOM-элемент. Обязательный аргумент.
 
-Возвращаемое значение: `{Boolean}`. Если искомый элемент найден – `true`.
+**Возвращаемое значение:** `Boolean`. Если искомый элемент найден – `true`.
+
+Пример:
 
 ```js
 modules.require(['dom', 'jquery'], function(dom, $) {
@@ -51,17 +55,17 @@ dom.contains($('.block1'), $('.block2'));  // true
 });
 ```
 
-
 <a name="fields-getFocused"></a>
+
 #### Метод `getFocused`
 
-Метод служит для получения ссылки на DOM-элемент, находящийся в фокусе. 
+Метод служит для получения ссылки на DOM-элемент, находящийся в фокусе.
 
 Не принимает аргументов.
 
-Возвращаемое значение: `{jQuery}` – объект в фокусе.
+**Возвращаемое значение:** `jQuery` – объект в фокусе.
 
-Например:
+Пример:
 
 ```js
 modules.require(['dom'], function(dom) {
@@ -71,17 +75,19 @@ dom.getFocused(); // ссылка на элемент в фокусе
 });
 ```
 
-
 <a name="fields-containsFocus"></a>
-#### Метод `containsFocus` 
+
+#### Метод `containsFocus`
 
 Метод проверяет находится ли в фокусе переданный аргументом DOM-элемент или один из его потомков.
 
-Принимаемые аргументы: 
+**Принимаемые аргументы:**
+
+* `domElem {jQuery}` – проверяемый DOM-элемент. Обязательный аргумент.
 
-* `domElem` `{jQuery}` – проверяемый DOM-элемент. Обязательный аргумент.
+**Возвращаемое значение:** `Boolean`. Если искомый элемент в фокусе – `true`.
 
-Возвращаемое значение: `{Boolean}`. Если искомый элемент в фокусе – `true`.
+Пример:
 
 ```js
 modules.require(['dom', 'jquery'], function(dom, $) {
@@ -98,17 +104,19 @@ dom.containsFocus($('.block1'));  // true
 });
 ```
 
-
 <a name="fields-isFocusable"></a>
+
 #### Метод `isFocusable`
 
 Метод проверят может ли браузер пользователя установить фокус на переданный аргументом DOM-элемент.   
 
-Принимаемые аргументы: 
+**Принимаемые аргументы:**
 
-* `domElem` `{jQuery}` – проверяемый DOM-элемент. Обязательный аргумент. Если в jQuery-цепочке несколько DOM-элементов, то проверяется первый из них.
+* `domElem {jQuery}` – проверяемый DOM-элемент. Обязательный аргумент. Если в jQuery-цепочке несколько DOM-элементов, то проверяется первый из них.
 
-Возвращаемое значение: `{Boolean}`. Если фокус может быть установлен – `true`.
+**Возвращаемое значение:** `Boolean`. Если фокус может быть установлен – `true`.
+
+Пример:
 
 ```js
 modules.require(['dom', 'jquery'], function(dom, $) {
@@ -129,20 +137,22 @@ dom.isFocusable($('.menu__item')); // true
 
 dom.isFocusable($('.menu__item')); // false
 
-}); 
+});
 ```
 
-
 <a name="fields-isEditable"></a>
+
 #### Метод `isEditable`
 
 Метод проверят возможен ли в переданном аргументом DOM-элементе ввод текста. Другими словами, с помощью метода можно проверить является ли элемент полем ввода, текстовой областью и т.п.
 
-Принимаемые аргументы: 
+**Принимаемые аргументы:**
+
+* `domElem {jQuery}` – проверяемый DOM-элемент. Обязательный аргумент. Если в jQuery-цепочке несколько DOM-элементов, то проверяется первый из них.
 
-* `domElem` `{jQuery}` – проверяемый DOM-элемент. Обязательный аргумент. Если в jQuery-цепочке несколько DOM-элементов, то проверяется первый из них.
+**Возвращаемое значение:** `Boolean`. Если ввод текста в элементе возможен – `true`.
 
-Возвращаемое значение: `{Boolean}`. Если ввод текста в элементе возможен – `true`.
+Пример:
 
 ```js
 modules.require(['dom', 'jquery'], function(dom, $) {

diff --git a/common.blocks/events/__channels/events__channels.ru.md b/common.blocks/events/__channels/events__channels.ru.md
@@ -1,3 +1,5 @@
+<a name="elems-channels"></a>
+
 # Элемент `channels` блока `events`
 
 Элемент `channels` блока `events` предназначен для работы с именованными каналами событий. Именные каналы позволяют организовать работу с событиями, используя шаблон проектирования «наблюдатель» (также известный как Publisher-subscriber).
@@ -8,15 +10,17 @@
 * получить ссылку на стандартный канал;
 * удалить канал – стандартный или по `id`.
 
-Принимаемые аргументы:
+**Принимаемые аргументы:**
+
+* [`id {String}`] – Идентификатор канала. Если не задан будет использоваться канал по умолчанию (`'default'`).
+* [`drop {Boolean}`] – Логический флаг, указывающий (в значении `true`) на необходимость удалить канал. По умолчанию `false`.
 
-* [`{String}` `id`] – Идентификатор канала. Если не задан будет использоваться канал по умолчанию (`'default'`).
-* [`{Boolean}` `drop`] – Логический флаг, указывающий (в значении `true`) на необходимость удалить канал. По умолчанию `false`.
+**Возвращаемое значение:**
 
-Возвращаемое значение:
+* `Object`. Объект «класса» `Emitter` – именной канал.
+* `undefined`. В случае если функция была вызвана с параметром `drop` в значении `true`.
 
-* `{Object}`. Объект «класса» `Emitter` – именной канал.
-* `{undefined}`. В случае если функция была вызвана с параметром `drop` в значении `true`.
+Пример:
 
 ```js
 modules.require(['events__channels'], function(channels) {