wrap_comments with a *numbered* markdown list

[anforowicz]

Repro steps

Step1: Prepare the following main.rs file as an input for rustfmt:

/// Bullet list:
///
/// - one one one one one one one one one one one one one one one one one one one one one one one
/// - two two two two two two two two two two two two two two two two two two two two two two two
///
/// Numbered list:
///
/// 1. one one one one one one one one one one one one one one one one one one one one one one one
/// 2. two two two two two two two two two two two two two two two two two two two two two two two
fn main() {
    println!("Hello, world!");
}

Note that the long lines are 98 characters long.

Step2: Run rustfmt --config wrap_comments=true src/main.rs

Note the usage of wrap_comments=true.

Expected behavior

Lists remain formatted as lists. This expectation is based on:

• https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#markdown which says that doc comments use https://commonmark.org/ and
• https://commonmark.org/help which seems to indicate that numbered lists should be supported with the format I've used above.

Actual behavior.

The list of bullet items remains formatted correctly, but the numbered list is no longer formatted as a list:

/// Bullet list:
///
/// - one one one one one one one one one one one one one one one one one one
///   one one one one one
/// - two two two two two two two two two two two two two two two two two two
///   two two two two two
///
/// Numbered list:
///
/// 1. one one one one one one one one one one one one one one one one one one
/// one one one one one 2. two two two two two two two two two two two two two
/// two two two two two two two two two two
fn main() {
    println!("Hello, world!");
}

I am observing the behavior above when using the following version of rustfmt:

$ rustfmt --version
rustfmt 1.4.38-nightly (4ca19e0 2022-04-19)

Workarounds

I guess I can insert a new line between numbered list items. Indentation will still get broken, but at least separate list items will remain separate.

Older, similar issues

A collegue has kindly pointed that there was a similar issue in the past (dealing with lists of bullet items): #3224

[ytmimi]

Thanks for the report.

rustfmt's support for markdown constructs is fairly limited, and there isn't any support for numbered lists. We currently handle bulleted lists (* and -) and block quotes (>) using the ItemizedBlock struct.

rustfmt/src/comment.rs

Lines 433 to 446 in c4416f2

	/// Block that is formatted as an item.
	///
	/// An item starts with either a star `*` a dash `-` or a greater-than `>`.
	/// Different level of indentation are handled by shrinking the shape accordingly.
	struct ItemizedBlock {
	/// the lines that are identified as part of an itemized block
	lines: Vec<String>,
	/// the number of characters (typically whitespaces) up to the item sigil
	indent: usize,
	/// the string that marks the start of an item
	opener: String,
	/// sequence of characters (typically whitespaces) to prefix new lines that are part of the item
	line_start: String,
	}

Maybe there's a way to minimally rework it to support numbered lists, but I'm not sure how difficult that would be.

[xxchan]

This issue can be closed

[ytmimi]

@xxchan thanks for pointing this out. The work was completed in #5423