[Feature Request] Skip formatting doc comments altogether when mixing sugared and de-sugared doc comments
Open
Nobody has claimed this yet.
A-comments
C-feature-request
P-low
- Dominant language
- Rust
- Stars
- 7k
- Forks
- 1.1k
- Avg merge
- 2d 13h
- Merged PRs (30d)
- 24
Description
Input:
//! <details open>
//! <summary>Example 1</summary>
//!
//! ```
#![doc = "test()"]
//! ```
//!
//! </details>
//!
//! <details open>
//! <summary>Example 2</summary>
//!
//! ```
//! example(2);
//! ```
//!
//! </details>
rustfmt +nightly --config format_code_in_doc_comments=true
Outputs:
//! <details open>
//! <summary>Example 1</summary>
//!
//! ```
#![doc = "test()"]
//! ```
//!
//! </details>
//!
//! <details open>
//! <summary>Example 2</summary>
//! ```
//! example(2);
//! ```
//!
//! </details>
Note no empty line before second example. So rustdoc of output looks like this:
Empty lines before backticks are important for Markdown.
HTML blocks in commonmark must end with empty line:
End condition: line is followed by a blank line
rustfmt 1.7.0-nightly (ca663b06 2024-01-08)
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
Reproduce the issue with the shown rustfmt nightly command and input, then trace the doc-comment formatting path. Add a regression test covering mixed sugared and de-sugared comments, with the expected output preserving the blank line before the second fenced block.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100