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!
-Here are some [good starting issues](https://github.com/nrc/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Aeasy).
+Here are some [good starting issues](https://github.com/rust-lang-nursery/rustfmt/issues?q=is%3Aopen+is%3Aissue+label%3Aeasy).
If you've found areas which need polish and don't have issues, please submit a
PR, don't feel there needs to be an issue.
### A quick tour of Rustfmt
-Rustfmt is basically a pretty printer - that is, it's mode of operation is to
+Rustfmt is basically a pretty printer - that is, its mode of operation is to
take an AST (abstract syntax tree) and print it in a nice way (including staying
under the maximum permitted width for a line). In order to get that AST, we
first have to parse the source text, we use the Rust compiler's parser to do
into the required width. How to handle this is up to the caller. Often the
caller just gives up, ultimately relying on the missed spans system to paste in
the un-formatted source. A better solution (although not performed in many
-places) is for the caller to shuffle around some of it's other items to make
+places) is for the caller to shuffle around some of its other items to make
more width, then call the function again with more space.
Since it is common for callers to bail out when a callee fails, we often use a
`create_config!` macro at the end of the file for all the options. The rest of
the file defines a bunch of enums used for options, and the machinery to produce
the config struct and parse a config file, etc. Checking an option is done by
-accessing the correct field on the config struct, e.g., `config.max_width`. Most
+accessing the correct field on the config struct, e.g., `config.max_width()`. Most
functions have a `Config`, or one can be accessed via a visitor or context of
some kind.
projects / rust.git / blobdiff