[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?