Rustfmt: Do not break long urls in comments.

Created on 20 Oct 2015 · 12Comments · Source: rust-lang/rustfmt

// https://github.com/rust-lang/rfcs/blob/master/text/0195-associated-items.md#encoding-higher-kinded-types

is format to this

// https://github.com/rust-lang/rfcs/blob/master/text/0195-associated-items.
// md#encoding-higher-kinded-types

a-comments only-with-option poor-formatting

Source

malbarbo

👍1

All 12 comments

What should we do with such comments?

marcusklaas on 20 Oct 2015

Leave it as it is. Break a url is bad because we cannot click it anymore...

malbarbo on 20 Oct 2015

👍1

We could try to break before the URL, if we are into breaking comments, otherwise leave as is.

nrc on 21 Oct 2015

Note that this also breaks in the case of the (style-guide-recommended) reference-style link, so this:

/// Here's a snippet talking about [higher-kinded types][1]. We might go on...

[1]: https://github.com/rust-lang/rfcs/blob/master/text/0195-associated-items.md#encoding-higher-kinded-types

becomes this:

/// Here's a snippet talking about [higher-kinded types][1]. We might go on...
///
/// [1]: https://github.com/rust-lang/rfcs/blob/master/text/0195-associated-
/// items.md#encoding-higher-kinded-types

I think the best solution is:

break before inline URLs if line-wrapping in comments of whatever variety
avoid wrapping at all in reference-style links

chriskrycho on 25 Oct 2015

There should be no breakings in reference-style links as this brakes formatting also:

/// Here's a snippet talking about [higher-kinded types][1]. We might go on...
///
/// [1]: https://short.example.link/ "Long description that will appear in hover on the link, this often contain description of page that is linked"

becomes this:

/// Here's a snippet talking about [higher-kinded types][1]. We might go on...
///
/// [1]: https://short.example.link/ "Long description that will appear in hover
/// on the link, this often contain description of page that is linked"

hauleth on 7 Nov 2015

This gets left as is by default, but the bug still exists if we turn on comment formatting

nrc on 6 Apr 2016

Closed by https://github.com/rust-lang-nursery/rustfmt/pull/911.

marcusklaas on 11 Apr 2016

When calling rustfmt on a file with:

//! For a quick overview see
//! [wikipedia](https://en.wikipedia.org/wiki/Bit_Manipulation_Instruction_Sets#BMI1_.28Bit_Manipulation_Instruction_Set_1.29).
//! The reference is [Intel 64 and IA-32 Architectures Software Developer's
//! Manual Volume 2: Instruction Set Reference,
//! A-Z](http://www.intel.de/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-instruction-set-reference-manual-325383.pdf).
//!

I get errors of the form:

Rustfmt failed at ...: line exceeded maximum length (sorry)
Rustfmt failed at ...: line exceeded maximum length (sorry)

Is this normal? Seems related to this issue but this issue is closed.

gnzlbg on 2 Aug 2016

👍1

It also seems to fail when an URL is in a list in a comment. For example here:

/// # Intrinsic (when available BMI1)
///
/// - [`BEXTR`](http://www.felixcloutier.com/x86/BEXTR.html): Bit field extract (supports 32/64 bit registers).
///

That could be formatted to something like

/// # Intrinsic (when available BMI1)
///
/// - [`BEXTR`](http://www.felixcloutier.com/x86/BEXTR.html): Bit field 
///   extract (supports 32/64 bit registers).
///

gnzlbg on 2 Aug 2016

👍1

I don't think #911 fixes this, because you split on punctuation.

As an example, the following:

/// See the [https://download.libsodium.org/doc/helpers/memory_management.html#guarded-heap-allocations](libsodium)
/// documentation for all of the security guarantees provided by this
/// function.

is converted to:

/// See the [https://download.libsodium.
/// org/doc/helpers/memory_management.
/// html#guarded-heap-allocations](libsodium)
/// documentation for all of the security guarantees provided by this
/// function.

stouset on 22 Oct 2016

Technically, markdown can handle URLs split over multiple lines, so rustfmt should actually follow markdown URL splitting style. rustdoc cannot currently handle this, but once that is fixed, this could be fixed too...

@malbarbo

Leave it as it is. Break a url is bad because we cannot click it anymore...

Why can't you click it anymore? Your editor should know that in Rust mode comments follow markdown, and thus recognize an URL even when its split across multiple line as long as the split follows markdown style.

gnzlbg on 28 Sep 2017

Triage: rustfmt no longer splits comments with URLs.