X-Git-Url: https://git.lizzy.rs/?a=blobdiff_plain;f=Contributing.md;h=9478bc89f3ba27b1906b20015b7ea238f31904a0;hb=01c14a2058924390543f072aeb5955a8d179df36;hp=50209a22d4759f97cb15a7286d205e22fb9e8d5e;hpb=7d4bdc646dd39c4efc82d3ca3f06ef9ec0cf009e;p=rust.git diff --git a/Contributing.md b/Contributing.md index 50209a22d47..9478bc89f3b 100644 --- a/Contributing.md +++ b/Contributing.md @@ -2,10 +2,12 @@ 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 -contributing or need help with anything, please ping nrc on irc, #rust-tools is -probably the best channel. Feel free to also ask questions on issues, or file -new issues specifically to get help. +contributing or need help with anything, please ping nrc on irc, #rust-dev-tools +on irc.mozilla.org is probably the best channel. Feel free to also ask questions +on issues, or file new issues specifically to get help. +All contributors are expected to follow our [Code of +Conduct](CODE_OF_CONDUCT.md). ## Test and file issues @@ -44,22 +46,28 @@ 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! -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%3Agood-first-issue). 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. @@ -81,11 +89,11 @@ wish there weren't. You can leave `FIXME`s, preferably with an issue number. ### 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 -that (see [src/lib.rs]). We shy away from doing anything too fancy, such as +that (see [src/lib.rs](src/lib.rs)). We shy away from doing anything too fancy, such as algebraic approaches to pretty printing, instead relying on an heuristic approach, 'manually' crafting a string for each AST node. This results in quite a lot of code, but it is relatively simple. @@ -100,7 +108,7 @@ format. There are different nodes for every kind of item and expression in Rust. For more details see the source code in the compiler - [ast.rs](https://dxr.mozilla.org/rust/source/src/libsyntax/ast.rs) - and/or the -[docs](http://manishearth.github.io/rust-internals-docs/syntax/ast/index.html). +[docs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast/index.html). Many nodes in the AST (but not all, annoyingly) have a `Span`. A `Span` is a range in the source code, it can easily be converted to a snippet of source @@ -125,19 +133,19 @@ 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 -mostly handled in [src/missed_spans.rs]. See also `FmtVisitor::last_pos` in -[src/visitor.rs]. +mostly handled in [src/missed_spans.rs](src/missed_spans.rs). See also `FmtVisitor::last_pos` in +[src/visitor.rs](src/visitor.rs). #### Some important elements At the highest level, Rustfmt uses a `Visitor` implementation called `FmtVisitor` -to walk the AST. This is in [src/visitor.rs]. This is really just used to walk +to walk the AST. This is in [src/visitor.rs](src/visitor.rs). This is really just used to walk items, rather than the bodies of functions. We also cover macros and attributes here. Most methods of the visitor call out to `Rewrite` implementations that then walk their own children. -The `Rewrite` trait is defined in [src/rewrite.rs]. It is implemented for many +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` @@ -174,33 +182,33 @@ know how to reformat, but more often it is because Rustfmt can't fit the item 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 -`try_opt!` macro to make this pattern more succinct. +`?` operator to make this pattern more succinct. One way we might find out that we don't have enough space is when computing how much 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 = try_opt!(budget.checked_sub(overhead))`. -`checked_sub` returns an `Option`, and if we would underflow `try_opt!` returns +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. Much 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 -code is a bit complex. Look in [src/lists.rs]. `write_list` is the key function, +code is a bit complex. Look in [src/lists.rs](src/lists.rs). `write_list` is the key function, and `ListFormatting` the key structure for configuration. You'll need to make a `ListItems` for input, this is usually done using `itemize_list`. Rustfmt strives to be highly configurable. Often the first part of a patch is creating a configuration option for the feature you are implementing. All -handling of configuration options is done in [src/config.rs]. Look for the +handling of configuration options is done in [src/config/mod.rs](src/config/mod.rs). Look for the `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.