[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).