From 94c95f5d1f3e1c7b62d0724ee07916fafc88389d Mon Sep 17 00:00:00 2001
From: Amy Boyd <amy@amyboyd.co.uk>
Date: Fri, 24 Jun 2016 21:21:08 +0100
Subject: [PATCH] Move documentation to a dedicated directory.

---
 docs/file-pattern-matchers.md | 26 ++++++++++++++++++++++++++
 docs/rules.md                 | 17 +++++++++++++++++
 editorconfig/path_matcher.go  | 18 ++++--------------
 3 files changed, 47 insertions(+), 14 deletions(-)
 create mode 100644 docs/file-pattern-matchers.md
 create mode 100644 docs/rules.md

diff --git a/docs/file-pattern-matchers.md b/docs/file-pattern-matchers.md
new file mode 100644
index 0000000..cf3af14
--- /dev/null
+++ b/docs/file-pattern-matchers.md
@@ -0,0 +1,26 @@
+This is how we convert a file pattern string found in a .editorconfig to a Go-compatible regex. This
+is done mostly according to the rules documented under "Wildcard Patterns" here:
+http://docs.editorconfig.org/en/master/editorconfig-format.html#patterns
+
+The are some differences to the official documentation, however.
+
+`*` Matches any string of characters, except path separators (/).
+
+`**` Matches any string of characters.
+
+`?` Matches any single character.
+
+`[seq]` Matches any single character in seq.
+
+`[!seq]` Matches any single character not in seq.
+
+`{s1,s2,s3}` Matches any of the strings given (separated by commas, can be nested).
+
+`{num1..num2}` Matches any integer numbers between num1 and num2, where num1 and num2 can be either positive or negative.
+
+**Differences from the official document**
+
+If file pattern is entirely `*`, according to the official documentation it should match files in the
+same directory and not in sub-directories (because `*` excludes path separators). However, in open
+source repositories I reviewed, a single `*` seems to be universally used to mean every file,
+instead of the technically-correct `**`. We adapt to what is used in the real world to be practical.
diff --git a/docs/rules.md b/docs/rules.md
new file mode 100644
index 0000000..d813493
--- /dev/null
+++ b/docs/rules.md
@@ -0,0 +1,17 @@
+The .editorconfig rules applied are according to the documentation found under "Supported Properties" here: http://docs.editorconfig.org/en/master/editorconfig-format.html#properties
+
+indent_style: set to "tab" or "space" to use hard tabs or soft tabs respectively. The values are case insensitive.
+
+indent_size: a whole number defining the number of columns used for each indentation level and the width of soft tabs (when supported). If this equals to "tab", the indent_size will be set to the tab size, which should be tab_width if tab_width is specified, or the tab size set by editor if tab_width is not specified. The values are case insensitive.
+
+tab_width: a whole number defining the number of columns used to represent a tab character. This defaults to the value of indent_size and should not usually need to be specified.
+
+end_of_line: set to "lf", "cr", or "crlf" to control how line breaks are represented. The values are case insensitive.
+
+charset: set to "latin1", "utf-8", "utf-8-bom", "utf-16be" or "utf-16le" to control the character set. Use of "utf-8-bom" is discouraged.
+
+trim_trailing_whitespace: set to "true" to remove any whitespace characters preceeding newline characters and "false" to ensure it doesn't.
+
+insert_final_newline: set to "true" ensure file ends with a newline when saving and "false" to ensure it doesn't.
+
+root: special property that should be specified at the top of the file outside of any sections. Set to "true" to stop .editorconfig files search on current file. The value is case insensitive.
diff --git a/editorconfig/path_matcher.go b/editorconfig/path_matcher.go
index ccc953c..416f5ab 100644
--- a/editorconfig/path_matcher.go
+++ b/editorconfig/path_matcher.go
@@ -1,17 +1,8 @@
 package editorconfig
 
 /*
- * Converts a string from a .editorconfig file to a Go-compatible regex, according to the rules
- * documented under "Wildcard Patterns" here:
- * http://docs.editorconfig.org/en/master/editorconfig-format.html#patterns
- *
- * *	Matches any string of characters, except path separators (/)
- * **	Matches any string of characters
- * ?	Matches any single character
- * [seq]	Matches any single character in seq
- * [!seq]	Matches any single character not in seq
- * {s1,s2,s3}	Matches any of the strings given (separated by commas, can be nested)
- * {num1..num2}	Matches any integer numbers between num1 and num2, where num1 and num2 can be either positive or negative
+ * Converts a string from a .editorconfig file to a Go-compatible regex. Refer to the documentation
+ * in `docs/file-pattern-matchers.md`
  */
 
 import (
@@ -31,9 +22,8 @@ var metaCharsRegexp = []*regexp.Regexp{
 
 func ConvertWildcardPatternToGoRegexp(pattern string) *regexp.Regexp {
 	if pattern == "*" {
-		// A single * seems to be universally used to mean every file, despite the official docs
-		// showing that ** is correct and * should only match top-level files. However, we adapt
-		// to what is used in the real world to be practical.
+		// As documented in `docs/file-pattern-matchers.md`, we deviate from the official
+		// documentation here and make * match every file.
 		return regexp.MustCompile(".")
 	}