-
Notifications
You must be signed in to change notification settings - Fork 888
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
Comments
What is left to stabilize this? |
Running this seemed to work well for me! |
I would like to use this as part of tokio and other crates, but I am hesitant to include unstable features at this point. |
In #3535 the option got renamed to |
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 /// ```rust
/// # fn foo() {if false{println!("hello")} // this function will be hidden
/// println!("Hello, World!");
/// ``` |
@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 |
I'd really like to see this feature stabilized. Are there any plans regarding it? |
This unstable feature has been renamed (See rust-lang/rustfmt#3348).
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>
This unstable feature has been renamed (See rust-lang/rustfmt#3348).
One thing I would really like with this is a separate EDIT: Actually, playing around with changing |
#5234 seems like a blocker for this. |
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? |
@tgross35 Normally things get merged as soon as they're ready, but we need to do a subtree sync with the |
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 I've linked several additional issues. I think we'd need to address each before we can move forward. |
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 |
It looks like this doesn't format snippets in item-level doc comments ( |
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:
//! Example module documentation.
//!
//! Using this crate is simple:
//!
//! ```
//! fn main () { println
//! ! ("Hello, world!")
//! ; }
//! ```
pub fn foo() {
println!("Hello, world!");
} Running IIRC, rustfmt doesn't touch code at all if it's unable to fit in the available |
I found an issue with cargo 1.79.0-nightly (d438c80c4 2024-03-19) and /// # 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:
but bot I'm not sure if I should report it as a separate ticket or just appending it here is OK...? |
@wiktor-k please open a new issue |
`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>
Tracking issue for unstable option:
format_code_in_doc_comments
The text was updated successfully, but these errors were encountered: