docs: reflect new packages in docs

Author: marionebl

@commitlint/format/README.md

@@ -1,11 +1,47 @@
-> Lint commit messages
+> Format commitlint reports
 
 # @commitlint/format
 
 ## Getting started
 
 ```shell
-npm install --save-dev @commitlint/format
+npm install --save @commitlint/format
+```
+
+## Example
+
+```js
+const format = require('@commitlint/format');
+
+format({
+  warnings: [
+    {
+      level: 0,
+      name: 'some-hint',
+      message: 'This will not show up as it has level 0'
+    },
+    {
+      level: 1,
+      name: 'some-warning',
+      message: 'This will show up yellow as it has level 1'
+    }
+  ],
+  errors: [
+    {
+      level: 2,
+      name: 'some-error',
+      message: 'This will show up red as it has level 2'
+    }
+  ]
+}, {
+  color: false
+});
+/* => [
+  '✖   This will show up red as it has level 2 [some-error]',
+  '    This will not show up as it has level 0 [some-hint]',
+  '⚠   This will show up yellow as it has level 1 [some-warning]',
+  '✖   found 1 problems, 2 warnings'
+] */
 ```
 
 Consult [docs/api](http://marionebl.github.io/commitlint/#/reference-api) for comprehensive documentation.

@commitlint/format/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@commitlint/format",
     "version": "6.1.0",
-    "description": "Lint your commit messages",
+    "description": "Format commitlint reports",
     "main": "lib/index.js",
     "files": [
       "lib/"

@commitlint/lint/README.md

@@ -1,11 +1,33 @@
-> Lint commit messages
+> Lint a string against commitlint rules
 
 # @commitlint/lint
 
 ## Getting started
 
 ```shell
-npm install --save-dev @commitlint/lint
+npm install --save @commitlint/lint
+```
+
+## Example
+
+```js
+const lint = require('@commitlint/lint');
+
+lint('foo: bar', {'type-enum': [1, 'always', ['foo']]})
+  .then(report => console.log(report));
+  // => { valid: true, errors: [], warnings: [] }
+
+lint('foo: bar', {'type-enum': [1, 'always', ['bar']]})
+  .then(report => console.log(report));
+  /* =>
+    { valid: true,
+      errors: [],
+      warnings:
+      [ { level: 1,
+          valid: false,
+          name: 'type-enum',
+          message: 'type must be one of [bar]' } ] }
+  */
 ```
 
 Consult [docs/api](http://marionebl.github.io/commitlint/#/reference-api) for comprehensive documentation.

@commitlint/lint/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@commitlint/lint",
     "version": "6.1.0",
-    "description": "Lint your commit messages",
+    "description": "Lint a string against commitlint rules",
     "main": "lib/index.js",
     "files": [
       "lib/"

@commitlint/load/README.md

@@ -1,4 +1,4 @@
-> Lint commit messages
+> Load shared commitlint configuration
 
 # @commitlint/load
 
@@ -8,4 +8,14 @@
 npm install --save-dev @commitlint/load
 ```
 
+## Example 
+
+```js
+const load = require('@commitlint/load');
+
+load({extends: ['./package']})
+.then(config => console.log(config));
+// => { extends: ['./package', './package-b'], rules: {} }
+```
+
 Consult [docs/api](http://marionebl.github.io/commitlint/#/reference-api) for comprehensive documentation.

@commitlint/load/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@commitlint/load",
     "version": "6.1.0",
-    "description": "Lint your commit messages",
+    "description": "Load shared commitlint configuration",
     "main": "lib/index.js",
     "files": [
       "lib/"

@commitlint/read/README.md

@@ -1,11 +1,27 @@
-> Lint commit messages
+> Read commit messages from a specified range or last edit
 
 # @commitlint/read
 
 ## Getting started
 
 ```shell
-npm install --save-dev @commitlint/read
+npm install --save @commitlint/read
+```
+
+## Example
+
+```js
+const read = require('@commitlint/read');
+
+// Read last edited commit message
+read({edit: true})
+    .then(messages => console.log(messages));
+    // => ['I did something\n\n']
+
+// Read from the third to second commit message from HEAD
+read({from: 'HEAD~2', to: 'HEAD~1'})
+  .then(messages => console.log(messages));
+  // => ['Initial commit\n\n']
 ```
 
 Consult [docs/api](http://marionebl.github.io/commitlint/#/reference-api) for comprehensive documentation.

@commitlint/read/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@commitlint/read",
     "version": "6.1.0",
-    "description": "Lint your commit messages",
+    "description": "Read commit messages from a specified range or last edit",
     "main": "lib/index.js",
     "files": [
       "lib/"

docs/reference-api.md

@@ -1,15 +1,16 @@
 # API
 
-## Install
+## @commitlint/format
+
+> Format commitlint reports
+
+### Install 
 
 ```
-npm install --save @commitlint/core
+npm install --save @commitlint/format
 ```
 
-## Methods
-
-### format
-> Format commitlint report data to a human-readable format
+### Usage
 
 * **Signature**
 
@@ -47,7 +48,7 @@ format(report?: Report = {}, options?: formatOptions = {}) => string[];
 * **Example**
 
 ```js
-const {format} = require('@commitlint/core');
+const format = require('@commitlint/format');
 
 format(); // => [ '\u001b[1m\u001b[32m✔\u001b[39m   found 0 problems, 0 warnings\u001b[22m' ]
 
@@ -82,9 +83,17 @@ format({
 ] */
 ```
 
-### load
+## @commitlint/load
+
+> Load shared commitlint configuration
+
+### Install 
 
-> load all relevant shared configuration
+```
+npm install --save @commitlint/load
+```
+
+### Usage
 
 * **Signature**
 
@@ -186,7 +195,7 @@ load(seed: Seed = {}) => Promise<Config>;
 * **Example**
 
 ```js
-const {load} = require('@commitlint/core');
+const load = require('@commitlint/load');
 
 load({
   rules: {
@@ -205,9 +214,17 @@ load({parserPreset: './parser-preset.js'})
 // => { extends: [], rules: {}, parserPreset: {name: './parser-preset.js', path: './parser-preset.js', opts: {}}}
 ```
 
-### read
+### @commitlint/read
 
-> Read commit messages from as specified range
+> Read commit messages from a specified range or disk
+
+### Install 
+
+```
+npm install --save @commitlint/read
+```
+
+### Usage
 
 * **Signature**
 
@@ -228,7 +245,7 @@ read(range: Range) => Promise<string[]>
 
 ```js
 // git commit -m "I did something"
-const {read} = require('@commitlint/core');
+const read = require('@commitlint/read');
 
 read({edit: true})
  .then(messages => console.log(messages));
@@ -249,6 +266,16 @@ read({from: 'HEAD~2', to: 'HEAD~1'})
 
 ### lint
 
+> Lint a string against commitlint rules
+
+### Install 
+
+```
+npm install --save @commitlint/lint
+```
+
+### Usage
+
 * **Signature**
 
 ```ts
@@ -284,7 +311,7 @@ lint(message: string, rules: {[ruleName: string]: Rule}, opts?: Options) => Prom
 * **Basic Example**
 
 ```js
-const {lint} = require('@commitlint/core');
+const lint = require('@commitlint/lint');
 
 lint('foo: bar')
   .then(report => console.log(report));
@@ -315,10 +342,11 @@ lint('foo-bar', {'type-enum': [2, 'always', ['foo']]}, opts).then(report => cons
 * **Load configuration**
 
 ```js
-const {lint, load} = require('@commitlint/core');
+const load = require('@commitlint/load');
+const lint = require('@commitlint/lint');
 
 const CONFIG = {
-  extends: ['./@commitlint/config-conventional']
+  extends: ['@commitlint/config-conventional']
 };
 
 load(CONFIG)
@@ -338,7 +366,8 @@ load(CONFIG)
 * **Read git history**
 
 ```js
-const {lint, read} = require('@commitlint/core');
+const lint = require('@commitlint/lint');
+const read = require('@commitlint/read');
 
 const RULES = {
   'type-enum': [2, 'always', ['foo']]
@@ -353,7 +382,9 @@ read({to: 'HEAD', from: 'HEAD~2'})
 * **Simplfied last-commit checker**
 
 ```js
-const {lint, load, read} = require('@commitlint/core');
+const load = require('@commitlint/load');
+const read = require('@commitlint/read');
+const lint = require('@commitlint/lint');
 
 Promise.all([load(), read({from: 'HEAD~1'})])
   .then(tasks => {