Documentation improvements (lesshint#335)

Author: jwilsson

README.md

@@ -3,29 +3,31 @@
 [![Build Status](https://travis-ci.org/lesshint/lesshint.svg?branch=master)](https://travis-ci.org/lesshint/lesshint)
 [![Build status](https://ci.appveyor.com/api/projects/status/d1u4477uxtv6dygk/branch/master?svg=true)](https://ci.appveyor.com/project/lesshint/lesshint/branch/master)
 [![Coverage Status](https://coveralls.io/repos/lesshint/lesshint/badge.svg?branch=master)](https://coveralls.io/r/lesshint/lesshint?branch=master)
-[![Dependency Status](https://david-dm.org/lesshint/lesshint.svg?theme=shields.io&style=flat)](https://david-dm.org/lesshint/lesshint)
-[![devDependency Status](https://david-dm.org/lesshint/lesshint/dev-status.svg?theme=shields.io&style=flat)](https://david-dm.org/lesshint/lesshint#info=devDependencies)
 
 `lesshint` is a tool to aid you in writing clean and consistent [Less](http://lesscss.org/).
 
-* [Requirements](#requirements)
 * [Installation](#installation)
 * [Configuration](#configuration)
-* [Custom linters](#custom-linters)
 * [CLI usage](#cli-usage)
+* [Linters](#linters)
 * [Reporters](#reporters)
-
-## Requirements
-[Node.js](https://nodejs.org/) 0.12 (or later) or [io.js](https://iojs.org/) 1.0 (or later).
+* [Developer resources](#developer-resources)
 
 ## Installation
-Run the following command from the command line (add `-g` to install globally):
+_[Node.js](https://nodejs.org/) 4 (or later) is required._
+
+Run the following from the command line to install `lesshint` (add `-g` to install globally):
 
 ```
 npm install lesshint
 ```
 
 ## Configuration
+<<<<<<< HEAD
+For information on how to configure `lesshint` and other available options, see the [user guide](/docs/user-guide/configuration.md).
+
+Since `lesshint` is highly customizable we recommend you to also take a look at the [available rule options](/lib/linters/README.md) to tailor it to your needs.
+=======
 `lesshint` is customizable and we highly recommend you to look at the [available options](lib/linters/README.md) to tailor it to your needs.
 
 Start by creating a `.lesshintrc` file in your project root and add your settings to it. It will be automatically loaded and merged with the default values.
@@ -193,6 +195,7 @@ We highly recommend the following resources which are all included with `lesshin
 * [postcss-less](https://github.com/webschik/postcss-less) - PostCSS Less plugin docs.
 * [postcss-selector-parser](https://github.com/postcss/postcss-selector-parser) - PostCSS plugin for working with selectors.
 * [postcss-values-parser](https://github.com/lesshint/postcss-values-parser) - PostCSS plugin for working with values.
+>>>>>>> master
 
 ## CLI usage
 Run `lesshint` from the command-line by passing one or more files/directories to recursively scan.
@@ -201,14 +204,14 @@ Run `lesshint` from the command-line by passing one or more files/directories to
 lesshint src/less/ lib/style.less
 ```
 
-Available Flags       | Description
-----------------------|----------------------------------------------
+Available Flags         | Description
+----------------------|---------------------
 `-c`/`--config`       | Specify the configuration file to use (will be merged with defaults).
 `-e`/`--exclude`      | A [minimatch glob pattern](https://github.com/isaacs/minimatch) or a file to exclude from being linted.
-`-l`/`--linters`      | Require paths of custom linters to add to the built-in list.
-`-r`/`--reporter`     | The reporter to use. See "Reporters" below for possible values.
-`-V`/`--version`      | Show version.
-`-x`/`--max-warnings` | Number of warnings to allow before exiting with a non-zero code. Passing `-1` will allow any number of warnings to pass.
+`-l`/`--linters`      | Paths to custom linters to add to the built-in list. See "Linters" below for more information.
+`-r`/`--reporter`     | The reporter to use. See "Reporters" below for more information.
+`-V`/`--version`      | Show the version.
+`-x`/`--max-warnings` | Number of warnings to allow before exiting with a non-zero code.
 
 ### Exit status codes
 Depending on the linter results and options supplied, the exit status code returned by the CLI will differ.
@@ -224,64 +227,17 @@ Exit status code   | Description
 
 These codes were chosen with regards to the [preferable exit codes](http://www.gsp.com/cgi-bin/man.cgi?section=3&topic=sysexits).
 
-## Reporters
-Reporters can be used to perform actions with the lint results, for example printing something to the terminal or generate custom reports.
-
-### The reporter loading steps
-
-1. If nothing is passed, a simple, default reporter will be used. This will just print all the warnings/errors found.
-2. Pass the name of a Node module. If `lesshint` is installed globally only globally installed reporters are available (the normal Node module loading rules apply).
-3. Pass a absolute or relative path to a custom reporter anywhere on the disk. Relative paths will be resolved against [`process.cwd()`](https://nodejs.org/api/process.html#process_process_cwd).
-
-These steps always apply, no matter whether you're using the CLI or calling `lesshint` from code.
-
-### Using reporters from the CLI
-```bash
-lesshint --reporter my-super-awesome-reporter file.less
-lesshint --reporter /path/to/my/super/awesome/reporter.js file.less
-```
-
-### Using reporters from code
-If you're writing code which utilizes `lesshint`, for example a Gulp plugin you can use the `getReporter` method on the `lesshint` object to load a reporter using the same logic as `lesshint` does.
-
-Pass the name of a module or a path to the `getReporter` method like this:
+## Linters
+In addition to the linters included with `lesshint`, it's also possible to include custom ones. For example to check something team or project specific.
 
-```js
-var defaultReporter = lesshint.getReporter(); //Or pass path to your custom reporter in getReporter
-var promise = lesshint.checkFile('my-less-file.less');
-
-promise.then(function(result){
-  defaultReporter.report(result);
-})
-```
+For more information on using custom linters, see the [user guide](/docs/user-guide/linters.md).
 
-### Writing your own reporter
-In its simplest form, a reporter is just a function accepting some input. The most basic reporter possible:
-
-```js
-module.exports = {
-    name: 'my-super-awesome-reporter', // Not required, but recommended
-    report: function (errors) {
-        console.log(errors.length ? 'Errors found' : 'No errors');
-    }
-};
-```
-
-The reporter will be passed an array of objects representing each error:
-
-```js
-{
-    column: 5,
-    file: 'file.less',
-    fullPath: 'path/to/file.less',
-    line: 1,
-    linter: 'spaceBeforeBrace',
-    message: 'Opening curly brace should be preceded by one space.',
-    severity: 'warning',
-    source: '.foo{'
-}
-```
+## Reporters
+Reporters are small modules that can be used to perform actions with the lint results, for example printing something to the terminal or generate custom reports.
 
-It's then up to the reporter to do something with the errors. No `return`s or anything are needed. If running from the CLI, `lesshint` will handle the setting of correct exit codes.
+For more information on using reporters, see the [user guide](/docs/user-guide/reporters.md).
 
-Take a look at the [default reporter](https://github.com/lesshint/lesshint/blob/master/lib/reporters/default.js) for more information.
+## Developer resources
+* [Node API](/docs/developer-guide/API.md) - `lesshint`'s public Node API reference.
+* [Developing linters](/docs/developer-guide/linters.md) - Guide for hacking on linters.
+* [Developing reporters](/docs/developer-guide/reporters.md) - Guide for hacking on reporters.

docs/developer-guide/API.md

@@ -0,0 +1,6 @@
+# Node API
+
+* [Lesshint class](/docs/developer-guide/api/lesshint.md)
+* [Runner class](/docs/developer-guide/api/runner.md)
+
+_Note: Anything not documented here should be considered a internal API which may change at any time._

docs/developer-guide/api/lesshint.md

@@ -0,0 +1,104 @@
+# Lesshint class
+
+The `Lesshint` class is the core of `lesshint`, from here all operations can be performed. To use it, start by initalizing a `lesshint` instance.
+
+```js
+const Lesshint = require('lesshint').Lesshint;
+
+const lesshint = new Lesshint();
+
+lesshint.configure();
+
+// Do your thing using the methods below
+```
+
+## `Lesshint.checkDirectory(checkPath)`
+Check a directory recursively. Will respect `fileExtensions` and `excludedFiles` options.
+
+A `Promise` will be returned.
+
+```js
+const result = lesshint.checkDirectory('/path/to/my/directory');
+
+result.then((results) => {
+
+});
+```
+
+## `Lesshint.checkFile(checkPath)`
+Check a single file asynchronously. Will not check `fileExtensions` and `excludedFiles` options.
+
+A `Promise` will be returned.
+
+```js
+const result = lesshint.checkFile('/path/to/my/file.less');
+
+result.then((results) => {
+
+});
+```
+
+## `Lesshint.checkPath(checkPath)`
+Check a path asynchronously. If a file is passed it will check that, if a directory is passed it will check that recursively. Will respect `fileExtensions` and `excludedFiles` options.
+
+A `Promise` will be returned.
+
+```js
+const result = lesshint.checkPath('/path/to/my/directory');
+
+result.then((results) => {
+
+});
+```
+
+## `Lesshint.checkString(input, checkPath)`
+Check a Less string synchronously and return an array of linter results.
+
+The `checkPath` argument can be used to include a file name in lint results.
+
+If a error occurs which isn't a Less parse error, an exception will be thrown.
+
+```js
+try {
+    const results = lesshint.checkString('<my less code>', '/path/to/file');
+} catch (e) {
+    console.error('Something bad happened.');
+}
+```
+
+## `Lesshint.configure(config)`
+Setup the options to use. This method must always be called before doing anything else, otherwise no options will be specified. Not even defaults.
+
+The `config` argument is optional, but if a object is passed it'll be merged with the defaults.
+
+```js
+const config = {
+    emptyRule: false
+};
+
+lesshint.configure(config);
+```
+
+## `Lesshint.getConfig(path)`
+Load a config file using `lesshint`'s logic.
+
+If `path` is a file, it'll be loaded and its contents returned. If `path` is a directory, it will start looking for a `.lesshintrc` file in that directory, traversing up the directory structure until it finds one. If no config file is found, `undefined` will be returned.
+
+```js
+const config = lesshint.getConfig('/path/to/my/config.json');
+```
+
+
+## `Lesshint.getReporter(reporter)`
+Load a reporter using `lesshint`'s logic.
+
+The `reporter` argument can be one of the following.
+* The name of a module. The normal Node.js loading rules for global/local modules apply.
+* Path to a reporter. Relative paths will be resolved against [`process.cwd()`](https://nodejs.org/api/process.html#process_process_cwd).
+* A already initialized reporter object which will just be returned again.
+
+If nothing is passed, the default reporter will be returned. If the reporter loading fails for some reason, `false` will be returned.
+
+```js
+const reporter = lesshint.getReporter('/path/to/my/reporter.js');
+```

docs/developer-guide/api/runner.md

@@ -0,0 +1,37 @@
+# Runner class
+
+The `Runner` class can be used to access the backbone of the CLI. To use it, start by initializing a `runner` instance.
+
+```js
+const Runner = require('lesshint').Runner;
+
+// Any CLI option is valid
+const options = {
+    maxWarnings: 10, // Dashes in CLI flags are converted to camel case
+    paths: ['file.less'] // An array of path(s) to check
+};
+
+const runner = new Runner(options);
+
+const result = runner.run();
+```
+
+## `Runner.constructor()`
+Set the options for a `Runner` instance.
+
+```js
+const runner = new Runner(options);
+```
+
+## `Runner.run()`
+Run `lesshint` as if used through the CLI. All rule checks will be performed and reporters called.
+
+A `Promise` will be returned. On success, it'll be resolved with a plain object. On failure, it'll be rejected with a `Runner` error object with a `status` property corresponding to a [CLI exit status code](/README.md#exit-status-codes).
+
+```js
+const result = runner.run();
+
+result.then((output) => {
+
+});
+```

docs/developer-guide/linters.md

@@ -0,0 +1,54 @@
+# Developing linters
+If you wish to create your own linter or work on one of the core ones, this is the place for you!
+
+First of all, in order to work properly, all linters are required to expose a few things.
+* `name` - The name of the linter. While we don't enforce namespaces, we recommend it when creating custom linters, to prevent naming collisions.
+* `nodeTypes` - An array of [PostCSS node types](http://api.postcss.org/postcss.html) that the linter wants to check.
+* `lint` - The main lint method which will be called with the following arguments.
+    * `config` - The config object for this linter.
+    * `node` - The current node to lint.
+
+If the linter doesn't find any errors or doesn't need/want to check the passed node for some reason it should return `undefined`. The linter doesn't need to check whether is's enabled or not, this will be checked beforehand by `lesshint`. If it's disabled, it'll never be called.
+
+If the linter finds something it should return an array of result objects which looks like this:
+
+```js
+{
+    column: 5,
+    file: 'file.less',
+    fullPath: '/path/to/file.less',
+    line: 1,
+    linter: 'spaceBeforeBrace',
+    message: 'Opening curly brace should be preceded by one space.',
+    position: 4,
+    severity: 'warning',
+    source: '.foo{'
+}
+```
+
+If a linter doesn't set a value for a property, `lesshint` will set it. Most of the time, you'll only want to set `column`, `line`, and `message` while leaving the rest to `lesshint`.
+
+A simple linter example:
+```js
+module.exports = {
+    name: 'my-namespace/my-super-awesome-linter',
+    nodeTypes: ['decl'],
+    lint: function (config, node) {
+        const results = [];
+
+        if (true) { // Nothing to lint, return early
+            return;
+        }
+
+        // Check some things...
+
+        // Return the results
+        return results;
+    }
+```
+
+When working with linters, we highly recommend the following resources which are all included with `lesshint`.
+* [postcss](http://api.postcss.org/postcss.html) - Main PostCSS docs.
+* [postcss-less](https://github.com/webschik/postcss-less) - PostCSS Less plugin docs.
+* [postcss-selector-parser](https://github.com/postcss/postcss-selector-parser) - PostCSS plugin for working with selectors.
+* [postcss-values-parser](https://github.com/lesshint/postcss-values-parser) - PostCSS plugin for working with values.