diff --git a/Configurations.md b/Configurations.md index 9b59b19acc5..577d62d29ad 100644 --- a/Configurations.md +++ b/Configurations.md @@ -1520,7 +1520,7 @@ mod dolor; mod sit; ``` -**Note** `mod` with `#[macro_export]` will not be reordered since that could change the semantic +**Note** `mod` with `#[macro_export]` will not be reordered since that could change the semantics of the original source code. ## `reorder_impl_items` diff --git a/Contributing.md b/Contributing.md index 23b3de3e8fa..3daaa3dd11e 100644 --- a/Contributing.md +++ b/Contributing.md @@ -1,7 +1,7 @@ # Contributing There are many ways to contribute to Rustfmt. This document lays out what they -are and has information for how to get started. If you have any questions about +are and has information on how to get started. If you have any questions about contributing or need help with anything, please ask in the WG-Rustfmt channel on [Discord](https://discordapp.com/invite/rust-lang). Feel free to also ask questions on issues, or file new issues specifically to get help. @@ -129,14 +129,14 @@ can. Our primary tool here is to look between spans for text we've missed. For example, in a function call `foo(a, b)`, we have spans for `a` and `b`, in this -case there is only a comma and a single space between the end of `a` and the +case, there is only a comma and a single space between the end of `a` and the start of `b`, so there is nothing much to do. But if we look at `foo(a /* a comment */, b)`, then between `a` and `b` we find the comment. At a higher level, Rustfmt has machinery so that we account for text between 'top level' items. Then we can reproduce that text pretty much verbatim. We only count spans we actually reformat, so if we can't format a span it is not missed -completely, but is reproduced in the output without being formatted. This is +completely but is reproduced in the output without being formatted. This is mostly handled in [src/missed_spans.rs](src/missed_spans.rs). See also `FmtVisitor::last_pos` in [src/visitor.rs](src/visitor.rs). @@ -152,7 +152,7 @@ then walk their own children. The `Rewrite` trait is defined in [src/rewrite.rs](src/rewrite.rs). It is implemented for many things that can be rewritten, mostly AST nodes. It has a single function, `rewrite`, which is called to rewrite `self` into an `Option`. The -arguments are `width` which is the horizontal space we write into, and `offset` +arguments are `width` which is the horizontal space we write into and `offset` which is how much we are currently indented from the lhs of the page. We also take a context which contains information used for parsing, the current block indent, and a configuration (see below). @@ -199,11 +199,11 @@ space we have. Something like `available_space = budget - overhead`. Since widths are unsized integers, this would cause underflow. Therefore we use checked subtraction: `available_space = budget.checked_sub(overhead)?`. `checked_sub` returns an `Option`, and if we would underflow `?` returns -`None`, otherwise we proceed with the computed space. +`None`, otherwise, we proceed with the computed space. ##### Rewrite of list-like expressions -Much syntax in Rust is lists: lists of arguments, lists of fields, lists of +Much of the syntax in Rust is lists: lists of arguments, lists of fields, lists of array elements, etc. We have some generic code to handle lists, including how to space them in horizontal and vertical space, indentation, comments between items, trailing separators, etc. However, since there are so many options, the diff --git a/Design.md b/Design.md index ccfc7227e75..00a7652aee0 100644 --- a/Design.md +++ b/Design.md @@ -63,15 +63,15 @@ Some details of the philosophy behind the implementation. ### Operate on the AST A reformatting tool can be based on either the AST or a token stream (in Rust -this is actually a stream of token trees, but its not a fundamental difference). +this is actually a stream of token trees, but it's not a fundamental difference). There are pros and cons to the two approaches. I have chosen to use the AST approach. The primary reasons are that it allows us to do more sophisticated manipulations, rather than just change whitespace, and it gives us more context when making those changes. -The advantage of the tokens approach are that you can operate on non-parsable +The advantage of the tokens approach is that you can operate on non-parsable code. I don't care too much about that, it would be nice, but I think being able -to perform sophisticated transformations is more important. In the future I hope to +to perform sophisticated transformations is more important. In the future, I hope to (optionally) be able to use type information for informing reformatting too. One specific case of unparsable code is macros. Using tokens is certainly easier here, but I believe it is perfectly solvable with the AST approach. At the limit, @@ -80,7 +80,7 @@ we can operate on just tokens in the macro case. I believe that there is not in fact that much difference between the two approaches. Due to imperfect span information, under the AST approach, we sometimes are reduced to examining tokens or do some re-lexing of our own. Under -the tokens approach you need to implement your own (much simpler) parser. I +the tokens approach, you need to implement your own (much simpler) parser. I believe that as the tool gets more sophisticated, you end up doing more at the token-level, or having an increasingly sophisticated parser, until at the limit you have the same tool. @@ -99,7 +99,7 @@ to good old fashioned abstraction and code sharing. This will give a bigger code base, but hopefully a better result. It also means that there will be some cases we can't format and we have to give -up. I think that is OK. Hopefully they are rare enough that manually fixing them +up. I think that is OK. Hopefully, they are rare enough that manually fixing them is not painful. Better to have a tool that gives great code in 99% of cases and fails in 1% than a tool which gives 50% great code and 50% ugly code, but never fails. @@ -150,9 +150,9 @@ for its configuration. Our visitor keeps track of the desired current indent due to blocks ( `block_indent`). Each `visit_*` method reformats code according to this indent, -`config.comment_width()` and `config.max_width()`. Most reformatting done in the -`visit_*` methods is a bit hacky and is meant to be temporary until it can be -done properly. +`config.comment_width()` and `config.max_width()`. Most reformatting that is done +in the `visit_*` methods is a bit hacky and is meant to be temporary until it can +be done properly. There are a bunch of methods called `rewrite_*`. They do the bulk of the reformatting. These take the AST node to be reformatted (this may not literally @@ -163,7 +163,7 @@ code in the box given by the indent and width budget. If the method fails, it returns `None` and the calling method then has to fallback in some way to give the callee more space. -So, in summary to format a node, we calculate the width budget and then walk down +So, in summary, to format a node, we calculate the width budget and then walk down the tree from the node. At a leaf, we generate an actual string and then unwind, combining these strings as we go back up the tree. diff --git a/README.md b/README.md index 17d5a5bd3e6..23111e12dbb 100644 --- a/README.md +++ b/README.md @@ -92,7 +92,7 @@ just need to run on the root file (usually mod.rs or lib.rs). Rustfmt can also read data from stdin. Alternatively, you can use `cargo fmt` to format all binary and library targets of your crate. -You can run `rustfmt --help` for information about argument. +You can run `rustfmt --help` for information about available arguments. When running with `--check`, Rustfmt will exit with `0` if Rustfmt would not make any formatting changes to the input, and `1` if Rustfmt would make changes. diff --git a/atom.md b/atom.md index 6fbb9546bb4..f77ac149072 100644 --- a/atom.md +++ b/atom.md @@ -13,7 +13,7 @@ Once installed a file is formatted with `ctrl-shift-c` or `cmd-shift-c`, also av Another way is to install [Beautify](https://atom.io/packages/atom-beautify), you can do this by running `apm install atom-beautify`. -There are 2 setting that need to be configured in the atom beautifier configuration. +There are 2 settings that need to be configured in the atom beautifier configuration. - Install rustfmt as per the [readme](README.md). - Open the atom beautifier settings