Updated docs about the loop and child components.

Author: gajus

README.md

@@ -16,7 +16,8 @@ React CSS Modules implement automatic mapping of CSS modules. Every CSS class is
         - [webpack](#webpack)
         - [Browserify](#browserify)
     - [Extending Component Styles](#extending-component-styles)
-    - [Styles Property](#styles-property)
+    - [`styles` Property](#styles-property)
+    - [Loops and Child Components](#loops-and-child-components)
     - [Decorator](#decorator)
     - [Options](#options)
         - [`allowMultiple`](#allowmultiple)
@@ -219,45 +220,99 @@ In this example, `table-custom-styles.css` selectively extends `table.css` (the
 
 Refer to the [`UsingStylesProperty` example](https://github.com/gajus/react-css-modules-examples/tree/master/src/UsingStylesProperty) for an example of a working implementation.
 
-### Styles Property
+### `styles` Property
 
 Decorated components inherit `styles` property that describes the mapping between CSS modules and CSS classes.
 
-`styles` property within the component itself is designed to be used only when `styleNames` cannot be used.
+```js
+class extends React.Component {
+    render () {
+        <div>
+            <p styleName='foo'></p>
+            <p className={this.props.styles.foo}></p>
+        </div>;
+    }
+}
+```
+
+In the above example, `styleName='foo'` and `className={this.props.styles.foo}` are equivalent.
+
+`styles` property is designed to enable component decoration of [Loops and Child Components](#loops-and-child-components).
+
+### Loops and Child Components
 
-`styleNames` cannot be used within a component to define styles of a `ReactElement` that will be generated by another component (https://github.com/gajus/react-css-modules/issues/11), e.g.
+`styleName` cannot be used to define styles of a `ReactElement` that will be generated by another component, e.g.
 
 ```js
-class extends React.Component {
+import React from 'react';
+import CSSModules from 'react-css-modules';
+import List from './List';
+import styles from './table.css';
+
+class CustomList extends React.Component {
     render () {
         let itemTemplate;
 
         itemTemplate = (name) => {
-            return <li styleName='foo'>{name}</li>;
+            return <li styleName='item-template'>{name}</li>;
         };
 
-        return <List itemTemplate={name} />;
+        return <List itemTemplate={itemTemplate} />;
     }
 }
+
+export default CSSModules(CustomList, styles);
 ```
 
-For that purpose, the decorated component inherits `styles` property that you can use just as a regular CSS Modules object. The earlier example can be therefore rewritten to:
+The above example will not work. `CSSModules` is used to decorate `CustomList` component. However, it is the `List` component that will render `itemTemplate`.
+
+For that purpose, the decorated component inherits [`styles` property](#styles-property) that you can use just as a regular CSS Modules object. The earlier example can be therefore rewritten to:
 
 ```js
-class extends React.Component {
+import React from 'react';
+import CSSModules from 'react-css-modules';
+import List from './List';
+import styles from './table.css';
+
+class CustomList extends React.Component {
     render () {
         let itemTemplate;
 
         itemTemplate = (name) => {
-            return <li styleName={this.props.styles.foo}>{name}</li>;
+            return <li className={this.props.styles['item-template']}>{name}</li>;
         };
 
-        return <List itemTemplate={name} />;
+        return <List itemTemplate={itemTemplate} />;
     }
 }
+
+export default CSSModules(CustomList, styles);
 ```
 
-`styles` property works with ES6 classes and stateless function components.
+You can use `styleName` property within the child component if you decorate the child component using `CSSModules` before passing it to the rendering component, e.g.
+
+```js
+import React from 'react';
+import CSSModules from 'react-css-modules';
+import List from './List';
+import styles from './table.css';
+
+class CustomList extends React.Component {
+    render () {
+        let itemTemplate;
+
+        itemTemplate = (name) => {
+            return <li styleName='item-template'>{name}</li>;
+        };
+
+        itemTemplate = CSSModules(itemTemplate, styles);
+
+        return <List itemTemplate={itemTemplate} />;
+    }
+}
+
+export default CSSModules(CustomList, styles);
+```
 
 ### Decorator