From 5dda986a2c6bd7e16f4f5a874de7bd7455d06c63 Mon Sep 17 00:00:00 2001
From: Stuart Dootson <stuart.dootson@gmail.com>
Date: Tue, 9 Aug 2016 22:11:27 +0200
Subject: [PATCH] Add commentary

---
 Contributing.md | 16 +++++++++++-----
 tests/system.rs |  7 ++++++-
 2 files changed, 17 insertions(+), 6 deletions(-)

diff --git a/Contributing.md b/Contributing.md
index 50b489cc130..7c66d27da41 100644
--- a/Contributing.md
+++ b/Contributing.md
@@ -44,17 +44,23 @@ colourised diff will be printed so that the offending line(s) can quickly be
 identified.
 
 Without explicit settings, the tests will be run using rustfmt's default
-configuration. It is possible to run a test using non-default settings by
-including configuration parameters in comments at the top of the file. For
-example: to use 3 spaces per tab, start your test with
+configuration. It is possible to run a test using non-default settings in several 
+ways. Firstly, you can include configuration parameters in comments at the top
+of the file. For example: to use 3 spaces per tab, start your test with
 `// rustfmt-tab_spaces: 3`. Just remember that the comment is part of the input,
 so include in both the source and target files! It is also possible to
 explicitly specify the name of the expected output file in the target directory.
-Use `// rustfmt-target: filename.rs` for this. Finally, you can use a custom
+Use `// rustfmt-target: filename.rs` for this. You can also specify a custom
 configuration by using the `rustfmt-config` directive. Rustfmt will then use
 that toml file located in `./tests/config/` for its configuration. Including
 `// rustfmt-config: small_tabs.toml` will run your test with the configuration
-file found at `./tests/config/small_tabs.toml`.
+file found at `./tests/config/small_tabs.toml`. The final option is used when the
+test source file contains no configuration parameter comments. In this case, the
+test harness looks for a configuration file with the same filename as the test
+file in the `./tests/config/` directory, so a test source file named `test-indent.rs`
+would need a configuration file named `test-indent.toml` in that directory. As an
+example, the `issue-1111.rs` test file is configured by the file
+`./tests/config/issue-1111.toml`.
 
 
 ## Hack!
diff --git a/tests/system.rs b/tests/system.rs
index 1e690c647a1..ce52bf5fd69 100644
--- a/tests/system.rs
+++ b/tests/system.rs
@@ -205,6 +205,9 @@ fn print_mismatches(result: HashMap<String, Vec<Mismatch>>) {
 
 fn read_config(filename: &str) -> Config {
     let sig_comments = read_significant_comments(&filename);
+    // Look for a config file... If there is a 'config' property in the significant comments, use
+    // that. Otherwise, if there are no significant comments at all, look for a config file with
+    // the same name as the test file.
     let mut config = if !sig_comments.is_empty() {
         get_config(sig_comments.get("config").map(|x| &(*x)[..]))
     } else {
@@ -253,7 +256,9 @@ pub fn idempotent_check(filename: String) -> Result<FormatReport, HashMap<String
     handle_result(write_result, target).map(|_| format_report)
 }
 
-// Reads test config file from comments and reads its contents.
+// Reads test config file using the supplied (optional) file name. If there's no file name or the
+// file doesn't exist, just return the default config. Otherwise, the file must be read
+// successfully.
 fn get_config(config_file: Option<&str>) -> Config {
     let config_file_name = match config_file {
         None => return Default::default(),