Cannot prohibit long code lines while allowing long doc lines
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 7k
- Forks
- 1.1k
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 24
Description
I have code that contains this:
//! If that's what you have and it works, you don't need this crate at all — you
//! can just use [`CARGO_BIN_EXE_<name>`][cargo-env].
//!
//! [cargo-env]: https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates
The last line is 132 characters long. The code also contains this:
fn get_cargo_env_or_panic(key: &str) -> OsString {
std::env::var_os(key).unwrap_or_else(||
panic!("The environment variable '{key}' is not set, is this running under a 'cargo test' command?")
)
}
The panic!() line is 117 characters long.
I would like to prohibit the overly long code line, because it can be fixed so that developers don't have to scroll the line to read it. This can be done with the following flags:
cargo fmt --all -- --check --config error_on_line_overflow=true --config error_on_unformatted=true
(Both are necessary.)
The good part is that these flags catch the line of code, which I can change to be formatted automatically. The bad part is that this flag also catches the URL in the comment, which I can't change to be formatted automatically.
To be honest, I'm not really sure what I'd expect, so here are some notes about it in no particular order:
- This seems related to #506, which also mentions that Markdown should allow breaking a URL across lines. I can't find any mention of this in any Markdown flavour documentation, and I can't find out how to get Rustdoc to do it. Arguably this is an issue with Rustdoc, if such a thing should be possible but either isn't, or isn't documented.
- Also related is #3863.
- This is for running in CI, so using the flags and ignoring the error I don't care about won't work in that context.
- Perhaps what would fix this is more fine-grained options, but I don't know what for. Overlong comments vs overlong code? But I still want to catch overlong comments that can be reflowed. Should Rustfmt identify that it's a URL and it can't be reflowed? That seems extremely specific. Does Rustfmt even "understand" Markdown?
Versions:
- Cargo
1.62 - Rustfmt
1.4.38-stable - Rustdoc
1.62.1
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reproducing the documented cargo fmt --all -- --check --config error_on_line_overflow=true --config error_on_unformatted=true command on the Rust and documentation examples. Read related issues #506 and #3863; done would require a clearly defined CI behavior that rejects reflowable overlong code while handling unbreakable documentation URLs appropriately.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- tooling
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100