src/tools/clippy/clippy_lints/src/tabs_in_doc_comments.rs

   1 use clippy_utils::diagnostics::span_lint_and_sugg;
   2 use rustc_ast::ast;
   3 use rustc_errors::Applicability;
   4 use rustc_lint::{EarlyContext, EarlyLintPass};
   5 use rustc_session::{declare_lint_pass, declare_tool_lint};
   6 use rustc_span::source_map::{BytePos, Span};
   7 use std::convert::TryFrom;
   8
   9 declare_clippy_lint! {
  10     /// ### What it does
  11     /// Checks doc comments for usage of tab characters.
  12     ///
  13     /// ### Why is this bad?
  14     /// The rust style-guide promotes spaces instead of tabs for indentation.
  15     /// To keep a consistent view on the source, also doc comments should not have tabs.
  16     /// Also, explaining ascii-diagrams containing tabs can get displayed incorrectly when the
  17     /// display settings of the author and reader differ.
  18     ///
  19     /// ### Example
  20     /// ```rust
  21     /// ///
  22     /// /// Struct to hold two strings:
  23     /// ///     - first         one
  24     /// ///     - second        one
  25     /// pub struct DoubleString {
  26     ///    ///
  27     ///    ///  - First String:
  28     ///    ///          - needs to be inside here
  29     ///    first_string: String,
  30     ///    ///
  31     ///    ///  - Second String:
  32     ///    ///          - needs to be inside here
  33     ///    second_string: String,
  34     ///}
  35     /// ```
  36     ///
  37     /// Will be converted to:
  38     /// ```rust
  39     /// ///
  40     /// /// Struct to hold two strings:
  41     /// ///     - first        one
  42     /// ///     - second    one
  43     /// pub struct DoubleString {
  44     ///    ///
  45     ///    ///     - First String:
  46     ///    ///         - needs to be inside here
  47     ///    first_string: String,
  48     ///    ///
  49     ///    ///     - Second String:
  50     ///    ///         - needs to be inside here
  51     ///    second_string: String,
  52     ///}
  53     /// ```
  54     #[clippy::version = "1.41.0"]
  55     pub TABS_IN_DOC_COMMENTS,
  56     style,
  57     "using tabs in doc comments is not recommended"
  58 }
  59
  60 declare_lint_pass!(TabsInDocComments => [TABS_IN_DOC_COMMENTS]);
  61
  62 impl TabsInDocComments {
  63     fn warn_if_tabs_in_doc(cx: &EarlyContext<'_>, attr: &ast::Attribute) {
  64         if let ast::AttrKind::DocComment(_, comment) = attr.kind {
  65             let comment = comment.as_str();
  66
  67             for (lo, hi) in get_chunks_of_tabs(&comment) {
  68                 // +3 skips the opening delimiter
  69                 let new_span = Span::new(
  70                     attr.span.lo() + BytePos(3 + lo),
  71                     attr.span.lo() + BytePos(3 + hi),
  72                     attr.span.ctxt(),
  73                     attr.span.parent(),
  74                 );
  75                 span_lint_and_sugg(
  76                     cx,
  77                     TABS_IN_DOC_COMMENTS,
  78                     new_span,
  79                     "using tabs in doc comments is not recommended",
  80                     "consider using four spaces per tab",
  81                     "    ".repeat((hi - lo) as usize),
  82                     Applicability::MaybeIncorrect,
  83                 );
  84             }
  85         }
  86     }
  87 }
  88
  89 impl EarlyLintPass for TabsInDocComments {
  90     fn check_attribute(&mut self, cx: &EarlyContext<'_>, attribute: &ast::Attribute) {
  91         Self::warn_if_tabs_in_doc(cx, attribute);
  92     }
  93 }
  94
  95 ///
  96 /// scans the string for groups of tabs and returns the start(inclusive) and end positions
  97 /// (exclusive) of all groups
  98 /// e.g. "sd\tasd\t\taa" will be converted to [(2, 3), (6, 8)] as
  99 ///       012 3456 7 89
 100 ///         ^-^  ^---^
 101 fn get_chunks_of_tabs(the_str: &str) -> Vec<(u32, u32)> {
 102     let line_length_way_to_long = "doc comment longer than 2^32 chars";
 103     let mut spans: Vec<(u32, u32)> = vec![];
 104     let mut current_start: u32 = 0;
 105
 106     // tracker to decide if the last group of tabs is not closed by a non-tab character
 107     let mut is_active = false;
 108
 109     // Note that we specifically need the char _byte_ indices here, not the positional indexes
 110     // within the char array to deal with multi-byte characters properly. `char_indices` does
 111     // exactly that. It provides an iterator over tuples of the form `(byte position, char)`.
 112     let char_indices: Vec<_> = the_str.char_indices().collect();
 113
 114     if let [(_, '\t')] = char_indices.as_slice() {
 115         return vec![(0, 1)];
 116     }
 117
 118     for entry in char_indices.windows(2) {
 119         match entry {
 120             [(_, '\t'), (_, '\t')] => {
 121                 // either string starts with double tab, then we have to set it active,
 122                 // otherwise is_active is true anyway
 123                 is_active = true;
 124             },
 125             [(_, _), (index_b, '\t')] => {
 126                 // as ['\t', '\t'] is excluded, this has to be a start of a tab group,
 127                 // set indices accordingly
 128                 is_active = true;
 129                 current_start = u32::try_from(*index_b).unwrap();
 130             },
 131             [(_, '\t'), (index_b, _)] => {
 132                 // this now has to be an end of the group, hence we have to push a new tuple
 133                 is_active = false;
 134                 spans.push((current_start, u32::try_from(*index_b).unwrap()));
 135             },
 136             _ => {},
 137         }
 138     }
 139
 140     // only possible when tabs are at the end, insert last group
 141     if is_active {
 142         spans.push((
 143             current_start,
 144             u32::try_from(char_indices.last().unwrap().0 + 1).expect(line_length_way_to_long),
 145         ));
 146     }
 147
 148     spans
 149 }
 150
 151 #[cfg(test)]
 152 mod tests_for_get_chunks_of_tabs {
 153     use super::get_chunks_of_tabs;
 154
 155     #[test]
 156     fn test_unicode_han_string() {
 157         let res = get_chunks_of_tabs(" \u{4f4d}\t");
 158
 159         assert_eq!(res, vec![(4, 5)]);
 160     }
 161
 162     #[test]
 163     fn test_empty_string() {
 164         let res = get_chunks_of_tabs("");
 165
 166         assert_eq!(res, vec![]);
 167     }
 168
 169     #[test]
 170     fn test_simple() {
 171         let res = get_chunks_of_tabs("sd\t\t\taa");
 172
 173         assert_eq!(res, vec![(2, 5)]);
 174     }
 175
 176     #[test]
 177     fn test_only_t() {
 178         let res = get_chunks_of_tabs("\t\t");
 179
 180         assert_eq!(res, vec![(0, 2)]);
 181     }
 182
 183     #[test]
 184     fn test_only_one_t() {
 185         let res = get_chunks_of_tabs("\t");
 186
 187         assert_eq!(res, vec![(0, 1)]);
 188     }
 189
 190     #[test]
 191     fn test_double() {
 192         let res = get_chunks_of_tabs("sd\tasd\t\taa");
 193
 194         assert_eq!(res, vec![(2, 3), (6, 8)]);
 195     }
 196
 197     #[test]
 198     fn test_start() {
 199         let res = get_chunks_of_tabs("\t\taa");
 200
 201         assert_eq!(res, vec![(0, 2)]);
 202     }
 203
 204     #[test]
 205     fn test_end() {
 206         let res = get_chunks_of_tabs("aa\t\t");
 207
 208         assert_eq!(res, vec![(2, 4)]);
 209     }
 210
 211     #[test]
 212     fn test_start_single() {
 213         let res = get_chunks_of_tabs("\taa");
 214
 215         assert_eq!(res, vec![(0, 1)]);
 216     }
 217
 218     #[test]
 219     fn test_end_single() {
 220         let res = get_chunks_of_tabs("aa\t");
 221
 222         assert_eq!(res, vec![(2, 3)]);
 223     }
 224
 225     #[test]
 226     fn test_no_tabs() {
 227         let res = get_chunks_of_tabs("dsfs");
 228
 229         assert_eq!(res, vec![]);
 230     }
 231 }