From 9b86e847b8addb128ee0929ce6729e4cbfe90c7d Mon Sep 17 00:00:00 2001
From: David Anson <david@dlaa.me>
Date: Wed, 18 Mar 2015 09:38:32 -0700
Subject: [PATCH] Improve config documentation, list parameter values and
 defaults.

---
 README.md    | 31 +++++++++++++++++++++++--------
 doc/Rules.md | 14 +++++++-------
 2 files changed, 30 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index c1fb0c16..845bc857 100644
--- a/README.md
+++ b/README.md
@@ -125,23 +125,38 @@ Configures the rules to use.
 Object keys are rule names and values are the rule's configuration.
 The value `false` disables a rule, `true` enables its default configuration,
 and passing an object customizes its settings. Setting the special `default`
-rule to `true` or `false` includes/excludes all rules by default.
+rule to `true` or `false` includes/excludes all rules by default. Enabling or
+disabling a tag name (ex: `whitespace`) affects all rules having that tag.
+
+The `default` rule is applied first, then keys are processed in order from top
+to bottom with later values overriding earlier ones.
 
 Example:
 
 ```json
 {
   "default": true,
-  "MD007": {
-    "indent": 4
-  },
-  "MD013": {
-    "line_length": 100
-  },
-  "MD029": false
+  "MD003": { "style": "atx_closed" },
+  "MD007": { "indent": 4 },
+  "MD009": false
+  "whitespace": false,
 }
 ```
 
+Sets of rules (known as a "style") can be stored separately and loaded as
+[JSON](http://en.wikipedia.org/wiki/JSON).
+
+Example:
+
+```js
+var options = {
+  "files": [ "..." ],
+  "config": require("style/relaxed.json")
+};
+```
+
+See the [style](style) directory for more samples.
+
 ### callback
 
 Type: `Function` taking (`Error`, `Object`)
diff --git a/doc/Rules.md b/doc/Rules.md
index 8a886eeb..1e4eb14f 100644
--- a/doc/Rules.md
+++ b/doc/Rules.md
@@ -53,7 +53,7 @@ The first header in the document should be a h1 header:
 
 Tags: headers
 
-Parameters: style
+Parameters: style ("consistent", "atx", "atx_closed", "setext"; default "consistent")
 
 This rule is triggered when different header styles (atx, setext, and 'closed'
 atx) are used in the same document:
@@ -79,7 +79,7 @@ document.
 
 Tags: bullet, ul
 
-Parameters: style
+Parameters: style ("consistent", "asterisk", "plus", "dash"; default "consistent")
 
 This rule is triggered when the symbols used in the document for unordered
 list items do not match the configured unordered list style:
@@ -149,7 +149,7 @@ characters if you use 4 space tabs, or 1 character if you use 2 space tabs).
 
 Tags: bullet, ul, indentation
 
-Parameters: indent
+Parameters: indent (number; default 2)
 
 This rule is triggered when list items are not indented by the configured
 number of spaces (default: 2).
@@ -244,7 +244,7 @@ lines inside code blocks.
 
 Tags: line_length
 
-Parameters: line_length
+Parameters: line_length (number; default 80)
 
 This rule is triggered when there are lines that are longer than the
 configured line length (default: 80 characters). To fix this, split the line
@@ -463,7 +463,7 @@ should be contained within this header.
 
 Tags: headers
 
-Parameters: punctuation
+Parameters: punctuation (string; default ".,;:!?")
 
 This rule is triggered on any header that has a punctuation character as the
 last character in the line:
@@ -531,7 +531,7 @@ separate blockquotes.
 
 Tags: ol
 
-Parameters: style
+Parameters: style ("one", "ordered"; default "one")
 
 This rule is triggered on ordered lists that do not either start with '1.' or
 do not have a prefix that increases in numerical order (depending on the
@@ -553,7 +553,7 @@ Example valid list if the style is configured as 'ordered':
 
 Tags: ol, ul, whitespace
 
-Parameters: ul_single, ol_single, ul_multi, ol_multi
+Parameters: ul_single, ol_single, ul_multi, ol_multi (number, default 1)
 
 This rule checks for the number of spaces between a list marker (e.g. '`-`',
 '`*`', '`+`' or '`1.`') and the text of the list item.