Update README and add configuration and debugging docs.

Author: allevato

Documentation/Configuration.md

@@ -0,0 +1,86 @@
+# `swift-format` Configuration
+
+`swift-format` allows users to configure a subset of its behavior, both when
+used as a command line tool or as an API.
+
+## Command Line Configuration
+
+A `swift-format` configuration file is a JSON file with the following
+top-level keys and values:
+
+*   `version` _(number)_: The version of the configuration file. For now, this
+    should always be `1`.
+
+*   `lineLength` _(number)_: The maximum allowed length of a line, in
+    characters.
+
+*   `indentation` _(object)_: The kind and amount of whitespace that should be
+    added when indenting one level. The object value of this property should
+    have **exactly one of the following properties:**
+
+    *   `spaces` _(number)_: One level of indentation is the given number of
+        spaces.
+    *   `tabs` _(number)_: One level of indentation is the given number of
+        tabs.
+
+*   `tabWidth` _(number)_: The number of spaces that should be considered
+    equivalent to one tab character. This is used during line length
+    calculations when tabs are used for indentation.
+
+*   `maximumBlankLines` _(number)_: The maximum number of consecutive blank
+    lines that are allowed to be present in a source file. Any number larger
+    than this will be collapsed down to the maximum.
+
+*   `respectsExistingLineBreaks` _(boolean)_: Indicates whether or not existing
+    line breaks in the source code should be honored (if they are valid
+    according to the style guidelines being enforced). If this settings is
+    `false`, then the formatter will be more "opinionated" by only inserting
+    line breaks where absolutely necessary and removing any others, effectively
+    canonicalizing the output.
+
+*   `blankLineBetweenMembers` _(object)_: Controls logic specific to the
+    enforcement of blank lines between type members. The object value of this
+    property has the following properties:
+
+    *   `ignoreSingleLineProperties` _(boolean)_: If `true`, then single-line
+        property declarations are allowed to appear consecutively without a
+        blank line separating them.
+
+> TODO: Add support for enabling/disabling specific syntax transformations in
+> the pipeline.
+
+### Example
+
+An example `.swift-format` configuration file is shown below.
+
+```javascript
+{
+    "version": 1,
+    "lineLength": 100,
+    "indentation": {
+        "spaces": 2
+    },
+    "maximumBlankLines": 1,
+    "respectsExistingLineBreaks": true,
+    "blankLineBetweenMembers": {
+        "ignoreSingleLineProperties": true
+    }
+}
+```
+
+## API Configuration
+
+The `SwiftConfiguration` module contains a `Configuration` type that is
+equivalent to the JSON structure described above. (In fact, `Configuration`
+conforms to `Codable` and is how the JSON form is read from and written to
+disk.)
+
+The `SwiftFormatter` and `SwiftLinter` APIs in the `SwiftFormat` module take a
+mandatory `Configuration` argument that specifies how the formatter should
+behave when acting upon source code or syntax trees.
+
+The default initializer for `Configuration` creates a value equivalent to the
+default configuration that would be printed by invoking
+`swift-format --mode dump-configuration`. API users can also provide their own
+configuration by modifying this value or loading it from another source using
+Swift's `Codable` APIs.

Documentation/Debugging.md

@@ -0,0 +1,14 @@
+# Debugging `swift-format`
+
+## Command Line Options
+
+`swift-format` provides some hidden command line options to facilitate
+debugging the tool during development:
+
+* `--debug-disable-pretty-print`: Disables the pretty-printing pass of the
+  formatter, causing only the syntax tree transformations in the first phase
+  pipeline to run.
+
+* `--debug-dump-token-stream`: Dumps a human-readable indented structure
+  representing the pseudotoken stream constructed by the pretty printing
+  phase.