Skip to content

Commit 8219457

Browse files
committed
Reflow suggests tests chapter
1 parent 9f8a854 commit 8219457

File tree

1 file changed

+23
-19
lines changed

1 file changed

+23
-19
lines changed

src/tests/suggest-tests.md

Lines changed: 23 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,39 @@
11
# Suggest tests tool
22

33
This chapter is about the internals of and contribution instructions for the
4-
`suggest-tests` tool. For a high-level overview of the tool, see
5-
[this section](../building/suggested.md#x-suggest). This tool is currently in a
6-
beta state and is tracked by [this](https://github.com/rust-lang/rust/issues/109933)
4+
`suggest-tests` tool. For a high-level overview of the tool, see [this
5+
section](../building/suggested.md#x-suggest). This tool is currently in a beta
6+
state and is tracked by [this](https://github.com/rust-lang/rust/issues/109933)
77
issue on Github. Currently the number of tests it will suggest are very limited
88
in scope, we are looking to expand this (contributions welcome!).
99

1010
## Internals
1111

12-
The tool is defined in a separate crate ([`src/tools/suggest-tests`](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests))
12+
The tool is defined in a separate crate
13+
([`src/tools/suggest-tests`](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests))
1314
which outputs suggestions which are parsed by a shim in bootstrap
1415
([`src/bootstrap/src/core/build_steps/suggest.rs`](https://github.com/rust-lang/rust/blob/master/src/bootstrap/src/core/build_steps/suggest.rs)).
15-
The only notable thing the bootstrap shim does is (when invoked with the
16-
`--run` flag) use bootstrap's internal mechanisms to create a new `Builder` and
17-
uses it to invoke the suggested commands. The `suggest-tests` crate is where the
18-
fun happens, two kinds of suggestions are defined: "static" and "dynamic"
16+
The only notable thing the bootstrap shim does is (when invoked with the `--run`
17+
flag) use bootstrap's internal mechanisms to create a new `Builder` and uses it
18+
to invoke the suggested commands. The `suggest-tests` crate is where the fun
19+
happens, two kinds of suggestions are defined: "static" and "dynamic"
1920
suggestions.
2021

2122
### Static suggestions
2223

23-
Defined [here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/static_suggestions.rs).
24-
Static suggestions are simple: they are just [globs](https://crates.io/crates/glob)
25-
which map to a `x` command. In `suggest-tests`, this is implemented with a
26-
simple `macro_rules` macro.
24+
Defined
25+
[here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/static_suggestions.rs).
26+
Static suggestions are simple: they are just
27+
[globs](https://crates.io/crates/glob) which map to a `x` command. In
28+
`suggest-tests`, this is implemented with a simple `macro_rules` macro.
2729

2830
### Dynamic suggestions
2931

30-
Defined [here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/dynamic_suggestions.rs).
32+
Defined
33+
[here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/dynamic_suggestions.rs).
3134
These are more complicated than static suggestions and are implemented as
32-
functions with the following signature: `fn(&Path) -> Vec<Suggestion>`. In
33-
other words, each suggestion takes a path to a modified file and (after running
35+
functions with the following signature: `fn(&Path) -> Vec<Suggestion>`. In other
36+
words, each suggestion takes a path to a modified file and (after running
3437
arbitrary Rust code) can return any number of suggestions, or none. Dynamic
3538
suggestions are useful for situations where fine-grained control over
3639
suggestions is needed. For example, modifications to the `compiler/xyz/` path
@@ -43,13 +46,14 @@ run.
4346
The following steps should serve as a rough guide to add suggestions to
4447
`suggest-tests` (very welcome!):
4548

46-
1. Determine the rules for your suggestion. Is it simple and operates only on
47-
a single path or does it match globs? Does it need fine-grained control over
49+
1. Determine the rules for your suggestion. Is it simple and operates only on a
50+
single path or does it match globs? Does it need fine-grained control over
4851
the resulting command or does "one size fit all"?
4952
2. Based on the previous step, decide if your suggestion should be implemented
5053
as either static or dynamic.
5154
3. Implement the suggestion. If it is dynamic then a test is highly recommended,
52-
to verify that your logic is correct and to give an example of the suggestion.
53-
See the [tests.rs](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/tests.rs)
55+
to verify that your logic is correct and to give an example of the
56+
suggestion. See the
57+
[tests.rs](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/tests.rs)
5458
file.
5559
4. Open a PR implementing your suggestion. **(TODO: add example PR)**

0 commit comments

Comments
 (0)