more updates to the docs

Author: ZeeCoder

docs/api.md

@@ -4,9 +4,11 @@
 
 **Instantiation**
 
-`new Container(element, stats, options)`
+```js
+new Container(element, meta, options)
+```
 
-Where `element` is an HTMLElement, `stats` is a json object from the PostCSS
+Where `element` is an HTMLElement, `meta` is a json object from the PostCSS
 plugin, and options are extra options about how the instance should behave.
 
 **Default options:**
@@ -49,10 +51,10 @@ window resize, if that fits your needs.
 ```js
 postCSS([
   containerQuery({
-    getJSON: function(cssFilePath, stats) {
+    getJSON: function(cssFilePath, meta) {
       // `cssFilePath`: the original css file's path that was processed. Useful
       // if you want to save the JSON relative to the original css.
-      // `stats`: the json stats having all the container-related data
+      // `meta`: the JSON metadata having all the container-related data
       // needed for the Container instances.
       // It's structure was previously described in the "Multiple Containers"
       // section.

docs/getting-started.md

@@ -2,7 +2,7 @@
 
 This solution consists of a PostCSS plugin and a JS (`Container`) class.
 
-> PostCSS plugin → Metadata → Runtime
+> PostCSS → Metadata → Runtime
 
 The plugin analyses your CSS and extracts all container query related
 data, producing a metadata JSON file.

docs/gulp.md

@@ -31,7 +31,7 @@ gulp.task("styles", () => {
 The above CSS can include multiple containers thanks to `singleContainer: false`,
 and [@define-container](docs/define-container.md) declarations.
 
-This task creates a styles.css and styles.json file, which can then be used by
-webpack as [you've seen it before](webpack-and-react.md).
+This task creates a `styles.css` and `styles.css.json` file, which can then be
+used by webpack as [you've seen it before](webpack-and-react.md).
 
 **Next:** [Multiple Containers](multiple-containers.md)

docs/multiple-containers.md

@@ -1,18 +1,17 @@
 # Multiple Containers
 
-Instead of processing each container individually, you might want to instead
-import all styles containing containers in a single file, and then process that.
-
-(This is the case described in [Usage with Gulp](gulp.md))
+Instead of processing each container individually, you might want to import all
+styles containing container query syntax in a single file, and process that.
 
 To do so, you'll have to switch off container auto-detection (which takes the
 first class found in a processed file as the selector for a container) to allow
 for the `@define-container;` declaration instead.
 
 With that, you'll be able to declare multiple containers in a single file.
 
-This is as simple as setting the `singleContainer` option to false, when using
-the postcss plugin.
+This is as simple as setting the `singleContainer` option to false.
+
+(Also showcased in the [Usage with Gulp](gulp.md)) section.)
 
 ### Example
 
@@ -30,21 +29,19 @@ the postcss plugin.
 // etc
 ```
 
-**JSON structure**
+**Metadata structure**
 
-Normally you don't have to care about the structure of the JSON file.
+Normally you don't have to care about the structure of the JSON meta file.
 (In fact, I encourage you not to depend on anything in it, as it could potentially
 change with new releases.)
 
-However, if you incorporate all you styles into a single file before processing
-it with the PostCSS plugin - using a workflow similar to what's described in
-[Usage with Gulp](gulp.md) for example -, you'll instead have the extracted
-container stats grouped by component selector in the resulting JSON:
+However, if you run the plugin in `singleContainer: false` mode, you'll have the
+extracted container metadata grouped by component selector in the resulting JSON:
 
 ```json
 {
-  ".Component1": {},
-  ".Component2": {}
+  ".Component1": {...},
+  ".Component2": {...}
 }
 ```
 

docs/syntax.md

@@ -5,7 +5,7 @@
 As previous examples show, containers can be declared by adding
 `@define-container;` inside a rule that's meant to be used as a container.
 
-(Unnecessary in `singleContainer` mode)
+(Unnecessary in `singleContainer` mode.)
 
 Multiple such definitions in a single CSS file are allowed. All container
 queries and units will be relative to the previous declaration.
@@ -137,8 +137,7 @@ done on each resize event (or `adjust` call).
 
 ### CSS Custom Properties
 
-Setting custom properties are supported, which you can use to improve
-performance.
+Setting custom properties are supported, which can be used to improve performance.
 
 ```pcss
 .User {

docs/without-webpack.md

@@ -1,16 +1,16 @@
 # Without webpack
 
 Even though the library was made with webpack in mind, there's no reason why
-other bundlers wouldn't work, or other UI libraries for that matter. (Instead
-of React.)
+other bundlers wouldn't work, or other UI libraries for that matter.
+(Ones other than of React.)
 
 **Just follow the same steps**
 
 1. Process your styles with the PostCSS plugin, to extract all container-related
    information
-2. Save the JSON(s) somewhere
-3. Serve the JSON(s) to the JS some way
-4. Create a Container instance for all container html elements
+2. Save the metadata file(s) somewhere
+3. Serve the file(s) to the runtime some way
+4. Create a `Container` instance for all container html elements
 
 For instance, imagine you have a `main.pcss` file, which imports all other
 components.
@@ -25,19 +25,19 @@ all elements found:
 // Assumptions:
 // - Browserify as the bundler
 // - JSON is available in a script tag, served by the backend:
-//   `<script type="application/json" id="container-stats">{ ... }</script>`
+//   `<script type="application/json" id="container-metadata">{ ... }</script>`
 
 import Container from "@zeecoder/container-query";
 
-const containerStats = JSON.parse(
-  document.getElementById("container-stats").textContent
+const meta = JSON.parse(
+  document.getElementById("container-metadata").textContent
 );
 
 // Initialising all containers by finding all instances based on the selectors
-for (let containerSelector in containerStats) {
+for (let containerSelector in meta) {
   document.querySelectorAll(containerSelector).forEach(element => {
-    // Initialising all HTML Elements with the right json stats
-    new Container(element, containerStats[containerSelector]);
+    // Initialising all HTML Elements with the right json metadata
+    new Container(element, meta[containerSelector]);
   });
 }
 ```