Update documentation #4345
Update documentation #4345
Conversation
This commit includes changes to the readme, cargo-fmt, and rustfmt
- Readme
- rearrange sections to an order I believe is a more natural
progression (this is opinionated, open to suggestions)
- add a TOC (I can add a CI test to ensure it's up to date, lmk what
you think)
- cargo-fmt
- link to config options
- rustfmt
- elaborate on operation with files/stdin
- include examples
- link to config options
Closes rust-lang#4336
| You can run `rustfmt --help` for information about available arguments. | ||
|
|
||
| You can run Rustfmt by just typing `rustfmt filename` if you used `cargo | ||
| install`. This runs rustfmt on the given file, if the file includes out of line | ||
| modules, then we reformat those too. So to run on a whole module or crate, you | ||
| 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. |
There was a problem hiding this comment.
This is the section that I'm most interested in updating to address #4336
There's items in the current text that are strictly not true, like the if the file includes out of line modules, then we reformat those too which is quite false with rustfmt 2.0 (so relevant for anyone building from source). Then there's other items like the if you used cargo install clause in the first sentence feels a bit dated/out of place (rustfmt filename is available regardless of whether you used rustup, installed from crates.io, or build from source).
Here's a high level framing and order of the items that IMO we should call out here, let me know what you think
cargo fmtis the easiest way to run rustfmt against your entire project and is the general recommendation, worth calling outcargo fmt --help. this is true for single-crate projects, but also cargo workspaces (not sure we necessarily need to call that out here)- Less commonly used, but rustfmt can also be used directly to format files (
rustfmt foo.rs bar.rs) or via stdin, but want to highlight the stdin bit more than the current text does
a. rustfmt 1.x will format out of line mods by default, sorustfmt rootfilewill basically format the entire project
b. rustfmt 2.x does not format out of line mods by default, requires--recursiveflag
There was a problem hiding this comment.
That sounds great to me, are you okay with the addition of this in a followup PR where I will also add changes to the running section?
There was a problem hiding this comment.
Yeah that's fine, but will want to keep #4336 open til after that
|
@calebcartwright sorry for the late response, I have been very busy ): ptal |
|
By the way, forgot to mention this earlier but really like the ordering of content. It's a conceptually simple change but does read much more fluidly now to me as well 👍 |
This time we try to clean up a lot of the README, after its structure was reorged in rust-lang#4345. cc @calebcartwright Closes rust-lang#4336
* Update documentation, round 2 This time we try to clean up a lot of the README, after its structure was reorged in #4345. cc @calebcartwright Closes #4336 * fixup! Update documentation, round 2
|
@calebcartwright says he'll likely overhaul the readme in 1.x anyway, backport not needed |
This commit includes changes to the readme, cargo-fmt, and rustfmt
progression (this is opinionated, open to suggestions)
you think)