src/librustdoc/passes/check_code_block_syntax.rs

   1 use errors::Applicability;
   2 use syntax::parse::lexer::{StringReader as Lexer};
   3 use syntax::token;
   4 use syntax::sess::ParseSess;
   5 use syntax::source_map::FilePathMapping;
   6 use syntax_pos::{InnerSpan, FileName};
   7
   8 use crate::clean;
   9 use crate::core::DocContext;
  10 use crate::fold::DocFolder;
  11 use crate::html::markdown::{self, RustCodeBlock};
  12 use crate::passes::Pass;
  13
  14 pub const CHECK_CODE_BLOCK_SYNTAX: Pass = Pass {
  15     name: "check-code-block-syntax",
  16     pass: check_code_block_syntax,
  17     description: "validates syntax inside Rust code blocks",
  18 };
  19
  20 pub fn check_code_block_syntax(krate: clean::Crate, cx: &DocContext<'_>) -> clean::Crate {
  21     SyntaxChecker { cx }.fold_crate(krate)
  22 }
  23
  24 struct SyntaxChecker<'a, 'tcx> {
  25     cx: &'a DocContext<'tcx>,
  26 }
  27
  28 impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> {
  29     fn check_rust_syntax(&self, item: &clean::Item, dox: &str, code_block: RustCodeBlock) {
  30         let sess = ParseSess::new(FilePathMapping::empty());
  31         let source_file = sess.source_map().new_source_file(
  32             FileName::Custom(String::from("doctest")),
  33             dox[code_block.code].to_owned(),
  34         );
  35
  36         let validation_status = {
  37             let mut has_syntax_errors = false;
  38             let mut only_whitespace = true;
  39             // even if there is a syntax error, we need to run the lexer over the whole file
  40             let mut lexer = Lexer::new(&sess, source_file, None);
  41             loop  {
  42                 match lexer.next_token().kind {
  43                     token::Eof => break,
  44                     token::Whitespace => (),
  45                     token::Unknown(..) => has_syntax_errors = true,
  46                     _ => only_whitespace = false,
  47                 }
  48             }
  49
  50             if has_syntax_errors {
  51                 Some(CodeBlockInvalid::SyntaxError)
  52             } else if only_whitespace {
  53                 Some(CodeBlockInvalid::Empty)
  54             } else {
  55                 None
  56             }
  57         };
  58
  59         if let Some(code_block_invalid) = validation_status {
  60             let mut diag = if let Some(sp) =
  61                 super::source_span_for_markdown_range(self.cx, &dox, &code_block.range, &item.attrs)
  62             {
  63                 let warning_message = match code_block_invalid {
  64                     CodeBlockInvalid::SyntaxError => "could not parse code block as Rust code",
  65                     CodeBlockInvalid::Empty => "Rust code block is empty",
  66                 };
  67
  68                 let mut diag = self.cx.sess().struct_span_warn(sp, warning_message);
  69
  70                 if code_block.syntax.is_none() && code_block.is_fenced {
  71                     let sp = sp.from_inner(InnerSpan::new(0, 3));
  72                     diag.span_suggestion(
  73                         sp,
  74                         "mark blocks that do not contain Rust code as text",
  75                         String::from("```text"),
  76                         Applicability::MachineApplicable,
  77                     );
  78                 }
  79
  80                 diag
  81             } else {
  82                 // We couldn't calculate the span of the markdown block that had the error, so our
  83                 // diagnostics are going to be a bit lacking.
  84                 let mut diag = self.cx.sess().struct_span_warn(
  85                     super::span_of_attrs(&item.attrs).unwrap_or(item.source.span()),
  86                     "doc comment contains an invalid Rust code block",
  87                 );
  88
  89                 if code_block.syntax.is_none() && code_block.is_fenced {
  90                     diag.help("mark blocks that do not contain Rust code as text: ```text");
  91                 }
  92
  93                 diag
  94             };
  95
  96             diag.emit();
  97         }
  98     }
  99 }
 100
 101 impl<'a, 'tcx> DocFolder for SyntaxChecker<'a, 'tcx> {
 102     fn fold_item(&mut self, item: clean::Item) -> Option<clean::Item> {
 103         if let Some(dox) = &item.attrs.collapsed_doc_value() {
 104             for code_block in markdown::rust_code_blocks(&dox) {
 105                 self.check_rust_syntax(&item, &dox, code_block);
 106             }
 107         }
 108
 109         self.fold_item_recur(item)
 110     }
 111 }
 112
 113 enum CodeBlockInvalid {
 114     SyntaxError,
 115     Empty,
 116 }