src/librustdoc/passes/check_code_block_syntax.rs

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