rust-lang / rust-lang/rust-bindgen
Bindgen produces #[doc = "foo\nbar"] doc comments instead of multiline doc comments
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 5.3k
- Forks
- 829
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 15
Description
This behavior changed in https://github.com/rust-lang/rust-bindgen/commit/f160d11d56007fe1b1125d04f0cb31af0b18fc6e
Bindgen used to produce doc comments like this:
extern "C" {
#[doc = "foo"]
#[doc = "bar"]
fn baz();
}
but now these doc comments look like this:
extern "C" {
#[doc = "foo\nbar"]
fn baz();
}
which is much less readable. We have documentation on normalizing doc comments, but not everyone is using a nightly rustfmt. This change does not seem intentional but rather collateral damage in that feature, perhaps it's worth bringing the old behavior back.
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 reviewing commit f160d11d56007fe1b1125d04f0cb31af0b18fc6e and the doc-comment normalization implementation it changed. Compare generated output for multiline comments with the examples in this issue; done means restoring the more readable multiline #[doc] output without losing the normalization behavior.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- tooling
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100