[unstable option] format_code_in_doc_comments

[scampi]

Tracking issue for unstable option: format_code_in_doc_comments

[carllerche]

What is left to stabilize this?

[shepmaster]

Running this seemed to work well for me!

[carllerche]

I would like to use this as part of tokio and other crates, but I am hesitant to include unstable features at this point.

[scampi]

In #3535 the option got renamed to format_code_in_doc_comment. With that maybe now is a good time to go through the stabilisation process for this option.

[JelteF]

This option is great. Would it be possible to use this to fix #2036 as well?

One thing I did notice is that it doesn't format code that is hidden by prefixing it with a #. It's not terrible but it would be nice if that was also formatted. So in this example the foo function is not formatted:

/// ```rust
/// # fn foo() {if false{println!("hello")} // this function will be hidden
/// println!("Hello, World!");
/// ```

[topecongiro]

One thing I did notice is that it doesn't format code that is hidden by prefixing it with a #. It's not terrible but it would be nice if that was also formatted. So in this example the foo function is not formatted:

@JelteF It's somewhat tricky to figure out the corresponding lines between the input and the output:

/// ```rust
/// # fn foo() {
/// # if false {
/// #     println!("hello")
/// # }
/// println!("Hello, World!");
/// ```

In the above example we need to add # prefix to cover the entire fn foo() { ... }.

[dianpopa]

In #3535 the option got renamed to format_code_in_doc_comment. With that maybe now is a good time to go through the stabilisation process for this option.

I'd really like to see this feature stabilized. Are there any plans regarding it?

[Nemo157]

One thing I would really like with this is a separate max_width setting. It appears it is using the standard max_width (not even the comment_width) but I much prefer using a max width of ~60 columns in examples as the space they are shown in in the documentation is commonly limited.

EDIT: Actually, playing around with changing max_width and comment_width don't seem to affect this at all.

[joshtriplett]

#5234 seems like a blocker for this.

[tgross35]

For #5234 there are actually two open PRs to fix them - #5235 and #5601. It looks like #5601 has more activity and is already marked as ready to merge (within the past week).

It also looks like #5533 is a bit of a blocker, PR #5536 is also marked ready to merge a bit over a month ago.

Other than that, I don't see anything that would block this, so am curious if anyone has another list. Anybody know when the "pr-ready-to-merge" labeled stuff gets flushed & merged?

[ytmimi]

Anybody know when the "pr-ready-to-merge" labeled stuff gets flushed & merged?

@tgross35 Normally things get merged as soon as they're ready, but we need to do a subtree sync with the rust-lang/rust repo, and have been holding off on merging PRs until we do the sync. The sync has been delayed while we wait for a few things to land upstream. Can't say for sure when those PRs will be merged, but hopefully soon!

[tgross35]

it seems like this is a great option to enable by default in a new edition, whenever that becomes possible. Discussed briefly in https://rust-lang.zulipchat.com/#narrow/stream/346005-t-style/topic/rustfmt.20editions

[tgross35]

#5601 was merged (woohoo!) so I think that only leaves #5536 (not sure why that didn't merge yet). Would this be ready to stabilize once that one clears?

[ytmimi]

@tgross35 I've linked several additional issues. I think we'd need to address each before we can move forward.

[tgross35]

Sorry, the mentions list is usually pretty noisy and I didn't realize they included blockers. Here's a summary I think, do you have permission to add to the main issue text?

• Issue: format_code_in_doc_comments makes multiline comments invalid #4421
  No fix yet
• Issue: format_code_in_doc_comments formats some long line comments to block comments #5533
  PR: Fix #5533: Prefer light_rewrite_comment if it is not a doccomment #5536
  PR approved, waiting on merge
• Issue: Trying to skip formatting in doc comments #5623
  PR: prevent unnecessary indent when formatting doc comment code snippets #5636
  PR waiting on review
• Issue: rustfmt cannot format code example with long #-hiding line #5627
  No fix yet

raw for copy+paste

- [ ] Issue: https://github.com/rust-lang/rustfmt/issues/4421
  No fix yet
- [ ] Issue: https://github.com/rust-lang/rustfmt/issues/5533
  PR: https://github.com/rust-lang/rustfmt/pull/5536
  PR approved, waiting on merge
- [ ] Issue: https://github.com/rust-lang/rustfmt/issues/5623
  PR: https://github.com/rust-lang/rustfmt/pull/5636
  PR waiting on review
- [ ] Issue: https://github.com/rust-lang/rustfmt/issues/5627
  No fix yet

[musjj]

It looks like this doesn't format snippets in item-level doc comments (//!). Is there an existing issue for this?

[archer-321]

Do you mean formatting in any doc comment that turns into an inner attribute? If so, formating seems to work at least for module doc comments:

lib.rs:

//! Example module documentation.
//!
//! Using this crate is simple:
//!
//! ```
//! fn main  () { println
//! ! ("Hello, world!")
//! ; }
//! ```

pub fn foo() {
    println!("Hello, world!");
}

Running cargo +nightly fmt -- --unstable-features --config format_code_in_doc_comments=true formats the code in the doc comment correctly.

IIRC, rustfmt doesn't touch code at all if it's unable to fit in the available max_width. I mostly had this problem with long strings, and enabling the unstable string formatting option mostly fixed doc comment formatting for my use cases. However, I noticed that --error-on-unformatted doesn't seem to work with code in doc comments 🤔

[wiktor-k]

I found an issue with cargo 1.79.0-nightly (d438c80c4 2024-03-19) and format_code_in_doc_comments = true with raw string literals:

/// # Examples
///
/// ```
/// use std::io::Write;
///
/// # fn main() -> testresult::TestResult {
/// let source = r#"```sh
/// echo x
/// ```"#;
/// let mut sink = Vec::new();
///
/// tangler::extract(source.as_bytes(), &mut sink, &["sh"])?;
///
/// assert_eq!(&b"echo x\n\n"[..], &sink[..]);
/// # Ok(()) }
/// ```

(Original source at https://github.com/wiktor-k/tangler/blob/main/src/lib.rs#L24-L26 . The tool works with markdown documents, that's why the doc comment uses raw strings).

It shows:

$ cargo +nightly fmt --all -- --check
error[E0748]: unterminated raw string
 --> <stdin>:5:18
  |
5 |     let source = r#"```sh
  |                  ^ unterminated raw string
  |
  = note: this raw string should be terminated with `"#`

but bot cargo test (nightly and stable) and cargo doc are OK with this fragment of code.

I'm not sure if I should report it as a separate ticket or just appending it here is OK...?

[ytmimi]

@wiktor-k please open a new issue