clippy_lints/src/tabs_in_doc_comments.rs

   1 use crate::utils::span_lint_and_sugg;
   2 use rustc_errors::Applicability;
   3 use rustc_lint::{EarlyContext, EarlyLintPass};
   4 use rustc_session::{declare_lint_pass, declare_tool_lint};
   5 use rustc_span::source_map::{BytePos, Span};
   6 use std::convert::TryFrom;
   7 use syntax::ast;
   8
   9 declare_clippy_lint! {
  10     /// **What it does:** Checks doc comments for usage of tab characters.
  11     ///
  12     /// **Why is this bad?** The rust style-guide promotes spaces instead of tabs for indentation.
  13     /// To keep a consistent view on the source, also doc comments should not have tabs.
  14     /// Also, explaining ascii-diagrams containing tabs can get displayed incorrectly when the
  15     /// display settings of the author and reader differ.
  16     ///
  17     /// **Known problems:** None.
  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     pub TABS_IN_DOC_COMMENTS,
  55     style,
  56     "using tabs in doc comments is not recommended"
  57 }
  58
  59 declare_lint_pass!(TabsInDocComments => [TABS_IN_DOC_COMMENTS]);
  60
  61 impl TabsInDocComments {
  62     fn warn_if_tabs_in_doc(cx: &EarlyContext<'_>, attr: &ast::Attribute) {
  63         if let ast::AttrKind::DocComment(comment) = attr.kind {
  64             let comment = comment.as_str();
  65
  66             for (lo, hi) in get_chunks_of_tabs(&comment) {
  67                 let new_span = Span::new(
  68                     attr.span.lo() + BytePos(lo),
  69                     attr.span.lo() + BytePos(hi),
  70                     attr.span.ctxt(),
  71                 );
  72                 span_lint_and_sugg(
  73                     cx,
  74                     TABS_IN_DOC_COMMENTS,
  75                     new_span,
  76                     "using tabs in doc comments is not recommended",
  77                     "consider using four spaces per tab",
  78                     "    ".repeat((hi - lo) as usize),
  79                     Applicability::MaybeIncorrect,
  80                 );
  81             }
  82         }
  83     }
  84 }
  85
  86 impl EarlyLintPass for TabsInDocComments {
  87     fn check_attribute(&mut self, cx: &EarlyContext<'_>, attribute: &ast::Attribute) {
  88         Self::warn_if_tabs_in_doc(cx, &attribute);
  89     }
  90 }
  91
  92 ///
  93 /// scans the string for groups of tabs and returns the start(inclusive) and end positions
  94 /// (exclusive) of all groups
  95 /// e.g. "sd\tasd\t\taa" will be converted to [(2, 3), (6, 8)] as
  96 ///       012 3456 7 89
  97 ///         ^-^  ^---^
  98 fn get_chunks_of_tabs(the_str: &str) -> Vec<(u32, u32)> {
  99     let line_length_way_to_long = "doc comment longer than 2^32 chars";
 100     let mut spans: Vec<(u32, u32)> = vec![];
 101     let mut current_start: u32 = 0;
 102
 103     // tracker to decide if the last group of tabs is not closed by a non-tab character
 104     let mut is_active = false;
 105
 106     let chars_array: Vec<_> = the_str.chars().collect();
 107
 108     if chars_array == vec!['\t'] {
 109         return vec![(0, 1)];
 110     }
 111
 112     for (index, arr) in chars_array.windows(2).enumerate() {
 113         let index = u32::try_from(index).expect(line_length_way_to_long);
 114         match arr {
 115             ['\t', '\t'] => {
 116                 // either string starts with double tab, then we have to set it active,
 117                 // otherwise is_active is true anyway
 118                 is_active = true;
 119             },
 120             [_, '\t'] => {
 121                 // as ['\t', '\t'] is excluded, this has to be a start of a tab group,
 122                 // set indices accordingly
 123                 is_active = true;
 124                 current_start = index + 1;
 125             },
 126             ['\t', _] => {
 127                 // this now has to be an end of the group, hence we have to push a new tuple
 128                 is_active = false;
 129                 spans.push((current_start, index + 1));
 130             },
 131             _ => {},
 132         }
 133     }
 134
 135     // only possible when tabs are at the end, insert last group
 136     if is_active {
 137         spans.push((
 138             current_start,
 139             u32::try_from(the_str.chars().count()).expect(line_length_way_to_long),
 140         ));
 141     }
 142
 143     spans
 144 }
 145
 146 #[cfg(test)]
 147 mod tests_for_get_chunks_of_tabs {
 148     use super::get_chunks_of_tabs;
 149
 150     #[test]
 151     fn test_empty_string() {
 152         let res = get_chunks_of_tabs("");
 153
 154         assert_eq!(res, vec![]);
 155     }
 156
 157     #[test]
 158     fn test_simple() {
 159         let res = get_chunks_of_tabs("sd\t\t\taa");
 160
 161         assert_eq!(res, vec![(2, 5)]);
 162     }
 163
 164     #[test]
 165     fn test_only_t() {
 166         let res = get_chunks_of_tabs("\t\t");
 167
 168         assert_eq!(res, vec![(0, 2)]);
 169     }
 170
 171     #[test]
 172     fn test_only_one_t() {
 173         let res = get_chunks_of_tabs("\t");
 174
 175         assert_eq!(res, vec![(0, 1)]);
 176     }
 177
 178     #[test]
 179     fn test_double() {
 180         let res = get_chunks_of_tabs("sd\tasd\t\taa");
 181
 182         assert_eq!(res, vec![(2, 3), (6, 8)]);
 183     }
 184
 185     #[test]
 186     fn test_start() {
 187         let res = get_chunks_of_tabs("\t\taa");
 188
 189         assert_eq!(res, vec![(0, 2)]);
 190     }
 191
 192     #[test]
 193     fn test_end() {
 194         let res = get_chunks_of_tabs("aa\t\t");
 195
 196         assert_eq!(res, vec![(2, 4)]);
 197     }
 198
 199     #[test]
 200     fn test_start_single() {
 201         let res = get_chunks_of_tabs("\taa");
 202
 203         assert_eq!(res, vec![(0, 1)]);
 204     }
 205
 206     #[test]
 207     fn test_end_single() {
 208         let res = get_chunks_of_tabs("aa\t");
 209
 210         assert_eq!(res, vec![(2, 3)]);
 211     }
 212
 213     #[test]
 214     fn test_no_tabs() {
 215         let res = get_chunks_of_tabs("dsfs");
 216
 217         assert_eq!(res, vec![]);
 218     }
 219 }