src/librustc_ast/util/comments.rs

   1 pub use CommentStyle::*;
   2
   3 use crate::ast;
   4 use rustc_span::source_map::SourceMap;
   5 use rustc_span::{BytePos, CharPos, FileName, Pos, Symbol};
   6
   7 use log::debug;
   8
   9 #[cfg(test)]
  10 mod tests;
  11
  12 #[derive(Clone, Copy, PartialEq, Debug)]
  13 pub enum CommentStyle {
  14     /// No code on either side of each line of the comment
  15     Isolated,
  16     /// Code exists to the left of the comment
  17     Trailing,
  18     /// Code before /* foo */ and after the comment
  19     Mixed,
  20     /// Just a manual blank line "\n\n", for layout
  21     BlankLine,
  22 }
  23
  24 #[derive(Clone)]
  25 pub struct Comment {
  26     pub style: CommentStyle,
  27     pub lines: Vec<String>,
  28     pub pos: BytePos,
  29 }
  30
  31 pub fn is_line_doc_comment(s: &str) -> bool {
  32     let res = (s.starts_with("///") && *s.as_bytes().get(3).unwrap_or(&b' ') != b'/')
  33         || s.starts_with("//!");
  34     debug!("is {:?} a doc comment? {}", s, res);
  35     res
  36 }
  37
  38 pub fn is_block_doc_comment(s: &str) -> bool {
  39     // Prevent `/**/` from being parsed as a doc comment
  40     let res = ((s.starts_with("/**") && *s.as_bytes().get(3).unwrap_or(&b' ') != b'*')
  41         || s.starts_with("/*!"))
  42         && s.len() >= 5;
  43     debug!("is {:?} a doc comment? {}", s, res);
  44     res
  45 }
  46
  47 // FIXME(#64197): Try to privatize this again.
  48 pub fn is_doc_comment(s: &str) -> bool {
  49     (s.starts_with("///") && is_line_doc_comment(s))
  50         || s.starts_with("//!")
  51         || (s.starts_with("/**") && is_block_doc_comment(s))
  52         || s.starts_with("/*!")
  53 }
  54
  55 pub fn doc_comment_style(comment: Symbol) -> ast::AttrStyle {
  56     let comment = &comment.as_str();
  57     assert!(is_doc_comment(comment));
  58     if comment.starts_with("//!") || comment.starts_with("/*!") {
  59         ast::AttrStyle::Inner
  60     } else {
  61         ast::AttrStyle::Outer
  62     }
  63 }
  64
  65 pub fn strip_doc_comment_decoration(comment: Symbol) -> String {
  66     let comment = &comment.as_str();
  67
  68     /// remove whitespace-only lines from the start/end of lines
  69     fn vertical_trim(lines: Vec<String>) -> Vec<String> {
  70         let mut i = 0;
  71         let mut j = lines.len();
  72         // first line of all-stars should be omitted
  73         if !lines.is_empty() && lines[0].chars().all(|c| c == '*') {
  74             i += 1;
  75         }
  76
  77         while i < j && lines[i].trim().is_empty() {
  78             i += 1;
  79         }
  80         // like the first, a last line of all stars should be omitted
  81         if j > i && lines[j - 1].chars().skip(1).all(|c| c == '*') {
  82             j -= 1;
  83         }
  84
  85         while j > i && lines[j - 1].trim().is_empty() {
  86             j -= 1;
  87         }
  88
  89         lines[i..j].to_vec()
  90     }
  91
  92     /// remove a "[ \t]*\*" block from each line, if possible
  93     fn horizontal_trim(lines: Vec<String>) -> Vec<String> {
  94         let mut i = usize::MAX;
  95         let mut can_trim = true;
  96         let mut first = true;
  97
  98         for line in &lines {
  99             for (j, c) in line.chars().enumerate() {
 100                 if j > i || !"* \t".contains(c) {
 101                     can_trim = false;
 102                     break;
 103                 }
 104                 if c == '*' {
 105                     if first {
 106                         i = j;
 107                         first = false;
 108                     } else if i != j {
 109                         can_trim = false;
 110                     }
 111                     break;
 112                 }
 113             }
 114             if i >= line.len() {
 115                 can_trim = false;
 116             }
 117             if !can_trim {
 118                 break;
 119             }
 120         }
 121
 122         if can_trim {
 123             lines.iter().map(|line| (&line[i + 1..line.len()]).to_string()).collect()
 124         } else {
 125             lines
 126         }
 127     }
 128
 129     // one-line comments lose their prefix
 130     const ONELINERS: &[&str] = &["///!", "///", "//!", "//"];
 131
 132     for prefix in ONELINERS {
 133         if comment.starts_with(*prefix) {
 134             return (&comment[prefix.len()..]).to_string();
 135         }
 136     }
 137
 138     if comment.starts_with("/*") {
 139         let lines =
 140             comment[3..comment.len() - 2].lines().map(|s| s.to_string()).collect::<Vec<String>>();
 141
 142         let lines = vertical_trim(lines);
 143         let lines = horizontal_trim(lines);
 144
 145         return lines.join("\n");
 146     }
 147
 148     panic!("not a doc-comment: {}", comment);
 149 }
 150
 151 /// Returns `None` if the first `col` chars of `s` contain a non-whitespace char.
 152 /// Otherwise returns `Some(k)` where `k` is first char offset after that leading
 153 /// whitespace. Note that `k` may be outside bounds of `s`.
 154 fn all_whitespace(s: &str, col: CharPos) -> Option<usize> {
 155     let mut idx = 0;
 156     for (i, ch) in s.char_indices().take(col.to_usize()) {
 157         if !ch.is_whitespace() {
 158             return None;
 159         }
 160         idx = i + ch.len_utf8();
 161     }
 162     Some(idx)
 163 }
 164
 165 fn trim_whitespace_prefix(s: &str, col: CharPos) -> &str {
 166     let len = s.len();
 167     match all_whitespace(&s, col) {
 168         Some(col) => {
 169             if col < len {
 170                 &s[col..]
 171             } else {
 172                 ""
 173             }
 174         }
 175         None => s,
 176     }
 177 }
 178
 179 fn split_block_comment_into_lines(text: &str, col: CharPos) -> Vec<String> {
 180     let mut res: Vec<String> = vec![];
 181     let mut lines = text.lines();
 182     // just push the first line
 183     res.extend(lines.next().map(|it| it.to_string()));
 184     // for other lines, strip common whitespace prefix
 185     for line in lines {
 186         res.push(trim_whitespace_prefix(line, col).to_string())
 187     }
 188     res
 189 }
 190
 191 // it appears this function is called only from pprust... that's
 192 // probably not a good thing.
 193 pub fn gather_comments(sm: &SourceMap, path: FileName, src: String) -> Vec<Comment> {
 194     let sm = SourceMap::new(sm.path_mapping().clone());
 195     let source_file = sm.new_source_file(path, src);
 196     let text = (*source_file.src.as_ref().unwrap()).clone();
 197
 198     let text: &str = text.as_str();
 199     let start_bpos = source_file.start_pos;
 200     let mut pos = 0;
 201     let mut comments: Vec<Comment> = Vec::new();
 202     let mut code_to_the_left = false;
 203
 204     if let Some(shebang_len) = rustc_lexer::strip_shebang(text) {
 205         comments.push(Comment {
 206             style: Isolated,
 207             lines: vec![text[..shebang_len].to_string()],
 208             pos: start_bpos,
 209         });
 210         pos += shebang_len;
 211     }
 212
 213     for token in rustc_lexer::tokenize(&text[pos..]) {
 214         let token_text = &text[pos..pos + token.len];
 215         match token.kind {
 216             rustc_lexer::TokenKind::Whitespace => {
 217                 if let Some(mut idx) = token_text.find('\n') {
 218                     code_to_the_left = false;
 219                     while let Some(next_newline) = &token_text[idx + 1..].find('\n') {
 220                         idx = idx + 1 + next_newline;
 221                         comments.push(Comment {
 222                             style: BlankLine,
 223                             lines: vec![],
 224                             pos: start_bpos + BytePos((pos + idx) as u32),
 225                         });
 226                     }
 227                 }
 228             }
 229             rustc_lexer::TokenKind::BlockComment { terminated: _ } => {
 230                 if !is_block_doc_comment(token_text) {
 231                     let code_to_the_right = match text[pos + token.len..].chars().next() {
 232                         Some('\r' | '\n') => false,
 233                         _ => true,
 234                     };
 235                     let style = match (code_to_the_left, code_to_the_right) {
 236                         (_, true) => Mixed,
 237                         (false, false) => Isolated,
 238                         (true, false) => Trailing,
 239                     };
 240
 241                     // Count the number of chars since the start of the line by rescanning.
 242                     let pos_in_file = start_bpos + BytePos(pos as u32);
 243                     let line_begin_in_file = source_file.line_begin_pos(pos_in_file);
 244                     let line_begin_pos = (line_begin_in_file - start_bpos).to_usize();
 245                     let col = CharPos(text[line_begin_pos..pos].chars().count());
 246
 247                     let lines = split_block_comment_into_lines(token_text, col);
 248                     comments.push(Comment { style, lines, pos: pos_in_file })
 249                 }
 250             }
 251             rustc_lexer::TokenKind::LineComment => {
 252                 if !is_doc_comment(token_text) {
 253                     comments.push(Comment {
 254                         style: if code_to_the_left { Trailing } else { Isolated },
 255                         lines: vec![token_text.to_string()],
 256                         pos: start_bpos + BytePos(pos as u32),
 257                     })
 258                 }
 259             }
 260             _ => {
 261                 code_to_the_left = true;
 262             }
 263         }
 264         pos += token.len;
 265     }
 266
 267     comments
 268 }