Overindented lines lint (similar to doc_lazy_continuation)
#13601
Comments
|
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 |
|
Thanks for taking a look!
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. |
Yeah, you're right.
Agreed. I'll probably take another look later. Thanks! |
|
Yeah, that last example in |
Align bullet points and improve indentation in the `Invariants` section
of the `GenDisk` struct documentation for better readability.
[ Yutaro is also working on implementing the lint we suggested to catch
this sort of issue in upstream Rust:
rust-lang/rust-clippy#13601
rust-lang/rust-clippy#13711
Thanks a lot! - Miguel ]
Fixes: 3253aba ("rust: block: introduce `kernel::block::mq` module")
Signed-off-by: Yutaro Ohno <[email protected]>
Reviewed-by: Boqun Feng <[email protected]>
Acked-by: Andreas Hindborg <[email protected]>
Link: https://lore.kernel.org/r/ZxkcU5yTFCagg_lX@ohnotp
Signed-off-by: Miguel Ojeda <[email protected]>
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
Could be written as:
The text was updated successfully, but these errors were encountered: