Overindented lines lint (similar to doc_lazy_continuation)

[ojeda]

What it does

The lint reports overindented lines, for instance in bullet lists (and potentially elsewhere?).

This could perhaps be considered a false negative of doc_lazy_continuation, but "lazy continuation lines" only cover removing indentation, not adding it.

Advantage

The advantages would be similar to doc_lazy_continuation:

• Clearer (easier to read) documentation in plain text form, i.e. unrendered, which is important in some projects.

• More consistency in documentation comments across a project (and across different projects, for those that enable the lint).

Drawbacks

No response

Example

/// - a
///    b
pub fn f() {}

Could be written as:

/// - a
///   b
pub fn f() {}

[ohno418]

Just a quick report for future work.

I was working on this for a bit, and found some difficulties in automatically applying this rule.

For example, doc like

/// - First line. Here's an sample object:
///   {
///      'protocol': 25,
///      'data': 0xffff
///   }
/// - Second line.

would be fixed into:

/// - First line. Here's an sample object:
///   {
///   'protocol': 25,
///   'data': 0xffff
///   }
/// - Second line.

Similar UI test exists here:

rust-clippy/tests/ui/doc/doc_lazy_list.rs

Lines 54 to 76 in ccf7c88

	/// * `protocol_descriptors`: A Json Representation of the ProtocolDescriptors
	/// to set up. Example:
	/// 'protocol_descriptors': [
	//~^ ERROR: doc list item without indentation
	/// {
	/// 'protocol': 25, # u64 Representation of ProtocolIdentifier::AVDTP
	/// 'params': [
	/// {
	/// 'data': 0x0103 # to indicate 1.3
	/// },
	/// {
	/// 'data': 0x0105 # to indicate 1.5
	/// }
	/// ]
	/// },
	/// {
	/// 'protocol': 1, # u64 Representation of ProtocolIdentifier::SDP
	/// 'params': [{
	/// 'data': 0x0019
	/// }]
	/// }
	/// ]
	//~^ ERROR: doc list item without indentation

[ojeda]

Thanks for taking a look!

For example, doc like

If I understand correctly, that doc is wrong but for other reasons, which makes it hard to offer fixes for; i.e. it should be e.g.

/// - First line. Here's an sample object:
///   ```json
///   {
///      'protocol': 25,
///      'data': 0xffff
///   }
///   ```
/// - Second line.

In any case, please note that even if the lint does not offer fixes (automatic or not), it would still be valuable to have it!

For instance, here it would have detected that broken documentation text.

[ohno418]

doc is wrong but for other reasons

Yeah, you're right.
So, it seems like doc in tests/ui/doc/doc_lazy_list.rs test is also wrong, and we should modify it together.

In any case, please note that even if the lint does not offer fixes (automatic or not), it would still be valuable to have it!

Agreed.

I'll probably take another look later. Thanks!

[ojeda]

Yeah, that last example in tests/ui/doc/doc_lazy_list.rs looks broken to me; however, it seems it was added to test for an ICE (from the comment linked there), i.e. it may be intentionally broken, which would be fine since it is a test. Thanks!