[unstable option] wrap_comments

[scampi]

Tracking issue for unstable option: wrap_comments

[carllerche]

What is left to stabilize this?

[scampi]

There is now a documented process describing stabilisation so we'd have to go through the conditions set there.

[benbrittain]

Is there a link to the stabilization process? I can't find it from the README.

I'd like to see us go through this process for the wrap_comments feature

[calebcartwright]

The process for stabilizing options is defined in https://github.com/rust-lang/rustfmt/blob/master/Processes.md

@scampi & @topecongiro - correct me if I'm wrong but my understanding is that the current focus is on rustfmt 2.0, and that stabilization of some of these currently-unstable config options won't come til after the 2.0 release (based on https://github.com/rust-lang/rustfmt/projects/2)

[jhpratt]

FWIW while I'd like to see this stabilized, this option can also break markdown. Last time I tried, a large markdown table I had was wrapped, which meant it was no longer valid markdown.

[bitdivine]

Is there a way of saying "Do not wrap this comment"? We have a similar problem with long maths formulae. It's not a blocker, it just takes a bit of effort to fix up the formulae afterwards, however it would be nice if we could make exceptions for some blocks of text. I suppose the markdown could be checked programatically before and after each conversion and the formatting could be skipped if the markdown is broken. That won't catch the formulae but it might help in your case @jhpratt . Maybe there is a nice markdown formatter out there in the wild that understands when it is looking at a table.

[daniel5151]

Any updates on this?

[jhpratt]

@daniel5151 Updates are posted as they come in. What you see in this thread is the current status.

[Nemo157]

Would it be plausible to split this into wrap_comments and wrap_doc_comments, and make wrap_doc_comments markdown aware?

[calebcartwright]

Would it be plausible to split this into wrap_comments and wrap_doc_comments, and make wrap_doc_comments markdown aware?

Could you elaborate a bit on the motivation? Is it just about wanting wrap_comments stabilized more quickly or are there cases where you'd want to wrap doc comments but not other comments or vice versa?

[Nemo157]

I actually don't care about normal comments much, I want to be able to have rustfmt wrap my doc comments. My thought was that normal comments aren't required to be markdown, so it would make sense to split the implementation.

[obsgolem]

The current implementation of this feature doesn't reflow short comments back into the lines above. Is this something that could be implemented?

[dcow]

This feature does not remove a leading blank comment line but it removes trailing blank lines.

///
/// Foo is a newtype for bar that can be passed to baz(foo) ...end of long line.
///
struct Foo ...

becomes

///
/// Foo is a newtype for bar that can be passed to baz(foo)
/// ...end of long line.
struct Foo ...

It's rather common to have an empty comment line before the associated section of code. It feels like this should at least be configurable.

[tgross35]

Just brainstorming here... there's an actively maintained library comrak that does markdown formatting, and allows setting line width. Could it make sense to use this on doc comments? It already has to be aware of things like tables and other markdown constructs, so I feel like it would do a better job out of the box than the current implementation.

Basically it seems like rustdoc needs some markdown-aware comment formatting, and it doesn't make sense to reinvent the wheel

Edit: more discussion on this at #5782

[luxalpa]

I would prefer a wrap_doc_comments because sometimes I comment out my code temporarily, and then the normal wrap_comments can do some very unfortunate wrapping (particularly on macros).

[VorpalBlade]

It would be good to be able to turn this off for specific comments or files. My use case for this is things like clap, bpaf or strum where doc strings are used to generate command line help output and I want precise control over the formatting in just those comments, while elsewhere I don't want to have to think about this and just have rustfmt do a sensible default.

For example I have this comment that is used (with strum::EnumMessage) to turn part of an enum into detailed documentation output:

pub(crate) enum Transform {
    // Other options here, elided for brevity...

    /// Get the value for a key from the system keyring. Useful for passwords
    /// etc that you do not want in your dotfiles repo.
    ///
    /// Arguments:
    /// * service="service-name"  (service name to find entry in the keyring)
    /// * user="user-name"        (username to find entry in the keyring)
    ///
    /// On Linux you can add an entry to the keyring using:
    /// secret-tool store --label="Descriptive name" service "service-name" username "user-name"
    #[strum(serialize = "keyring")]
    Keyring,
}

Rustfmt with wrap_comments wants to wrap the line with the secret-tool command. Since this is not used as markdown (it is used as plain text on stdout), putting this is a markdown code block doesn't really work (well, at least not without post-processing to filter that out).

[sww1235]

@VorpalBlade would using #[rustfmt::skip] work for your use case?

[c-git]

I would prefer a wrap_doc_comments because sometimes I comment out my code temporarily, and then the normal wrap_comments can do some very unfortunate wrapping (particularly on macros).

+1 for this. I just came here this. I've been using wrap_comments daily now and it's been really good. I've been happy just typing and all the wrapping gets taken care off automatically until today when I had long lines of code with calls to the error tracing macro that I commented out temporarily and now tried to uncomment to find that all my macros got line wrapped. I have no idea how this could be addressed but this is IMO a surprising problem. Obvious after you think about it but not acceptable on stable rust IMO. New users coming in would do as they normally do comment out code and be surprised when they try to uncomment it.

[JarredAllen]

I have a proposal for an alternate solution to wrap_comments wrapping people's code:

Personally, whenever I have a comment that I want to persist in the code, I use // ..-style comments. But when I'm commenting out some snippet of code, I instead use /* .. */-style comments. So, an option to format only the // ..-style comments would (for me, at least) fix the issue of it rewrapping macros while temporarily commented-out.

I'm not sure how many people use the same scheme as me, maybe y'all should 👍 if this option would work for y'all, and 👎 if you use comments differently such that it wouldn't?

EDIT: Wow, I didn't think I'd be that weird

[DianaNites]

To workaround this I generally just don't comment out blocks of code at all, but use normal blocks and cfg those out.

fn foo() {
    // <some code here>
}

to

fn foo() {
    #[cfg(no)]
    {
        // <some code here, correctly formatted and IDE highlighted, and collapsible as a single region,
        // now slightly rightward>
    }
}

at item level, I use an inline module instead of expression blocks.

[Lokathor]

that works and i used to to it, but some part of rust screams at unknown configs by default these days.

[DianaNites]

Yeah that is annoying, project boilerplate both new and existing but newly updated now includes adding it to check-cfg. At least once #[cfg(true/false)] is stabilized it'll Just Work without needing to be manually added, but only on newer rustc. rust-lang/rust#131204

[c-git]

Those are great work a rounds but I'm saying that for people new to rust that is not exactly approachable. I'm not the only person that highlights a some lines of code the Ctrl + / in my IDE. It's a surprising thing to have that then get broken by the formatter so that it cannot just be uncommented

[danielparks]

TL;DR: do any of the above ideas need to block stabilization of this as it is now?

I don't think this issue is about making comment wrapping on by default, correct? It’s just about stabilizing the option.

Does (should?) an option to limit comment wrapping to doc comments, or //-style comments, or whatever, block the stabilization of a general option to wrap comments?

I suppose there could be some bike-shedding around how to configure those other options, but it seems like simply stabilizing the current functionality wouldn't really get in the way of developing those other options in the future.