Merge pull request #111 from bem-sdk/docs/serialization

docs: serialization

Author: blond

README.md

@@ -26,6 +26,7 @@ Contents
 * [Install](#install)
 * [Usage](#usage)
 * [API](#api)
+* [Serialization](#serialization)
 * [TypeScript support](#typescript-support)
 * [Debuggability](#debuggability)
 * [Deprecation](#deprecation)
@@ -270,7 +271,7 @@ buttonTextBoldName.belongsTo(buttonName);     // false
 
 ### valueOf()
 
-Returns object representing the entity name.
+Returns normalized object representing the entity name.
 
 ```js
 const BemEntityName = require('@bem/entity-name');
@@ -283,7 +284,15 @@ name.valueOf();
 
 ### toJSON()
 
-Returns object for `JSON.stringify()` purposes.
+Returns raw data for `JSON.stringify()` purposes.
+
+```js
+const BemEntityName = require('@bem/entity-name');
+
+const name = new BemEntityName({ block: 'input', mod: 'available' });
+
+JSON.stringify(name); // {"block":"input","mod":{"name":"available","val":true}}
+```
 
 ### toString()
 
@@ -354,6 +363,31 @@ BemEntityName.isBemEntityName(entityName); // true
 BemEntityName.isBemEntityName({ block: 'button' }); // false
 ```
 
+Serialization
+-------------
+
+The `BemEntityName` has `toJSON` method to support `JSON.stringify()` behaviour.
+
+Use `JSON.stringify` to serialize an instance of `BemEntityName`.
+
+```js
+const BemEntityName = require('@bem/entity-name');
+
+const name = new BemEntityName({ block: 'input', mod: 'available' });
+
+JSON.stringify(name); // {"block":"input","mod":{"name":"available","val":true}}
+```
+
+Use `JSON.parse` to deserialize JSON string and create an instance of `BemEntityName`.
+
+```js
+const BemEntityName = require('@bem/entity-name');
+
+const str = '{"block":"input","mod":{"name":"available","val":true}}';
+
+new BemEntityName(JSON.parse(str)); // BemEntityName({ block: 'input', mod: 'available' });
+```
+
 TypeScript support
 ------------------
 
@@ -390,18 +424,6 @@ console.log(`name: ${name}`);
 // ➜ name: input_available
 ```
 
-Also `BemEntityName` has `toJSON` method to support `JSON.stringify()` behaviour.
-
-```js
-const BemEntityName = require('@bem/entity-name');
-
-const name = new BemEntityName({ block: 'input', mod: 'available' });
-
-console.log(JSON.stringify(name));
-
-// ➜ {"block":"input","mod":{"name":"available","val":true}}
-```
-
 Deprecation
 -----------
 

lib/entity-name.js

@@ -284,7 +284,7 @@ class BemEntityName {
     }
 
     /**
-     * Returns object representing the entity name. Is needed for debug in Node.js.
+     * Returns normalized object representing the entity name.
      *
      * In some browsers `console.log()` calls `valueOf()` on each argument.
      * This method will be called to get custom string representation of the object.
@@ -305,7 +305,14 @@ class BemEntityName {
     valueOf() { return this._data; }
 
     /**
-     * Return raw data for `JSON.stringify()`.
+     * Returns raw data for `JSON.stringify()` purposes.
+     *
+     * @example
+     * const BemEntityName = require('@bem/entity-name');
+     *
+     * const name = new BemEntityName({ block: 'input', mod: 'available' });
+     *
+     * JSON.stringify(name); // {"block":"input","mod":{"name":"available","val":true}}
      *
      * @returns {BemSDK.EntityName.StrictRepresentation}
      */