Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[unstable option] format_code_in_doc_comments #3348

Open
Tracked by #83
scampi opened this issue Feb 13, 2019 · 19 comments
Open
Tracked by #83

[unstable option] format_code_in_doc_comments #3348

scampi opened this issue Feb 13, 2019 · 19 comments
Labels
unstable option tracking issue of an unstable option

Comments

@scampi
Copy link
Contributor

scampi commented Feb 13, 2019

Tracking issue for unstable option: format_code_in_doc_comments

@scampi scampi added the unstable option tracking issue of an unstable option label Feb 13, 2019
@scampi scampi changed the title [unstable option] unstable option: format_doc_comments [unstable option] format_doc_comments Feb 13, 2019
@carllerche
Copy link
Member

What is left to stabilize this?

@shepmaster
Copy link
Member

Running this seemed to work well for me!

@carllerche
Copy link
Member

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
Copy link
Contributor Author

scampi commented May 16, 2019

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
Copy link

JelteF commented Nov 2, 2019

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
Copy link
Contributor

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
Copy link

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?

elrnv added a commit to elrnv/ron that referenced this issue Apr 18, 2020
This unstable feature has been renamed (See
rust-lang/rustfmt#3348).
bors bot added a commit to ron-rs/ron that referenced this issue Apr 20, 2020
212: Update format_doc_comments to format_code_in_doc_comments r=kvark a=elrnv

Update unstable rustfmt feature `format_doc_comments` to its new name (See
rust-lang/rustfmt#3348).

Co-authored-by: Egor Larionov <egor.larionov@gmail.com>
kvark pushed a commit to ron-rs/ron that referenced this issue Apr 20, 2020
@Nemo157
Copy link
Member

Nemo157 commented Oct 6, 2020

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.

@ytmimi ytmimi changed the title [unstable option] format_doc_comments [unstable option] format_code_in_doc_comment Jul 26, 2022
@ytmimi ytmimi changed the title [unstable option] format_code_in_doc_comment [unstable option] format_code_in_doc_comments Jul 27, 2022
@joshtriplett
Copy link
Member

#5234 seems like a blocker for this.

@tgross35
Copy link
Contributor

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
Copy link
Contributor

ytmimi commented Nov 19, 2022

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
Copy link
Contributor

tgross35 commented Dec 2, 2022

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
Copy link
Contributor

#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
Copy link
Contributor

ytmimi commented Mar 15, 2023

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

@tgross35
Copy link
Contributor

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?

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
Copy link

musjj commented Apr 6, 2024

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

@archer-321
Copy link

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
Copy link

wiktor-k commented Apr 9, 2024

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
Copy link
Contributor

ytmimi commented Apr 9, 2024

@wiktor-k please open a new issue

DDtKey added a commit to testcontainers/testcontainers-rs-modules-community that referenced this issue Aug 21, 2024
`format_code_in_doc_comments` is a nightly `rustfmt` feature. (tracking
issue: rust-lang/rustfmt#3348)
I think this might be helpfull.

Usually, I would not consider this being an option, but given that
already some other `rustfmt` feature are enabled... 😉

---------

Co-authored-by: Artem Medvedev <i@ddtkey.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
unstable option tracking issue of an unstable option
Projects
None yet
Development

No branches or pull requests