src/librustdoc/passes/html_tags.rs

   1 use super::{span_of_attrs, Pass};
   2 use crate::clean::*;
   3 use crate::core::DocContext;
   4 use crate::fold::DocFolder;
   5 use crate::html::markdown::opts;
   6 use core::ops::Range;
   7 use pulldown_cmark::{Event, Parser};
   8 use rustc_feature::UnstableFeatures;
   9 use rustc_session::lint;
  10
  11 pub const CHECK_INVALID_HTML_TAGS: Pass = Pass {
  12     name: "check-invalid-html-tags",
  13     run: check_invalid_html_tags,
  14     description: "detects invalid HTML tags in doc comments",
  15 };
  16
  17 struct InvalidHtmlTagsLinter<'a, 'tcx> {
  18     cx: &'a DocContext<'tcx>,
  19 }
  20
  21 impl<'a, 'tcx> InvalidHtmlTagsLinter<'a, 'tcx> {
  22     fn new(cx: &'a DocContext<'tcx>) -> Self {
  23         InvalidHtmlTagsLinter { cx }
  24     }
  25 }
  26
  27 pub fn check_invalid_html_tags(krate: Crate, cx: &DocContext<'_>) -> Crate {
  28     if !UnstableFeatures::from_environment().is_nightly_build() {
  29         krate
  30     } else {
  31         let mut coll = InvalidHtmlTagsLinter::new(cx);
  32
  33         coll.fold_crate(krate)
  34     }
  35 }
  36
  37 const ALLOWED_UNCLOSED: &[&str] = &[
  38     "area", "base", "br", "col", "embed", "hr", "img", "input", "keygen", "link", "meta", "param",
  39     "source", "track", "wbr",
  40 ];
  41
  42 fn drop_tag(
  43     tags: &mut Vec<(String, Range<usize>)>,
  44     tag_name: String,
  45     range: Range<usize>,
  46     f: &impl Fn(&str, &Range<usize>),
  47 ) {
  48     if let Some(pos) = tags.iter().position(|(t, _)| *t == tag_name) {
  49         for _ in pos + 1..tags.len() {
  50             if ALLOWED_UNCLOSED.iter().find(|&at| at == &tags[pos + 1].0).is_some() {
  51                 continue;
  52             }
  53             // `tags` is used as a queue, meaning that everything after `pos` is included inside it.
  54             // So `<h2><h3></h2>` will look like `["h2", "h3"]`. So when closing `h2`, we will still
  55             // have `h3`, meaning the tag wasn't closed as it should have.
  56             f(&format!("unclosed HTML tag `{}`", tags[pos + 1].0), &tags[pos + 1].1);
  57             tags.remove(pos + 1);
  58         }
  59         tags.remove(pos);
  60     } else {
  61         // It can happen for example in this case: `<h2></script></h2>` (the `h2` tag isn't required
  62         // but it helps for the visualization).
  63         f(&format!("unopened HTML tag `{}`", tag_name), &range);
  64     }
  65 }
  66
  67 fn extract_tag(
  68     tags: &mut Vec<(String, Range<usize>)>,
  69     text: &str,
  70     range: Range<usize>,
  71     f: &impl Fn(&str, &Range<usize>),
  72 ) {
  73     let mut iter = text.chars().enumerate().peekable();
  74
  75     while let Some((start_pos, c)) = iter.next() {
  76         if c == '<' {
  77             let mut tag_name = String::new();
  78             let mut is_closing = false;
  79             while let Some((pos, c)) = iter.peek() {
  80                 // Checking if this is a closing tag (like `</a>` for `<a>`).
  81                 if *c == '/' && tag_name.is_empty() {
  82                     is_closing = true;
  83                 } else if c.is_ascii_alphanumeric() && !c.is_ascii_uppercase() {
  84                     tag_name.push(*c);
  85                 } else {
  86                     if !tag_name.is_empty() {
  87                         let r = Range { start: range.start + start_pos, end: range.start + pos };
  88                         if is_closing {
  89                             drop_tag(tags, tag_name, r, f);
  90                         } else {
  91                             tags.push((tag_name, r));
  92                         }
  93                     }
  94                     break;
  95                 }
  96                 iter.next();
  97             }
  98         }
  99     }
 100 }
 101
 102 impl<'a, 'tcx> DocFolder for InvalidHtmlTagsLinter<'a, 'tcx> {
 103     fn fold_item(&mut self, item: Item) -> Option<Item> {
 104         let hir_id = match self.cx.as_local_hir_id(item.def_id) {
 105             Some(hir_id) => hir_id,
 106             None => {
 107                 // If non-local, no need to check anything.
 108                 return None;
 109             }
 110         };
 111         let dox = item.attrs.collapsed_doc_value().unwrap_or_default();
 112         if !dox.is_empty() {
 113             let cx = &self.cx;
 114             let report_diag = |msg: &str, range: &Range<usize>| {
 115                 let sp = match super::source_span_for_markdown_range(cx, &dox, range, &item.attrs) {
 116                     Some(sp) => sp,
 117                     None => span_of_attrs(&item.attrs).unwrap_or(item.source.span()),
 118                 };
 119                 cx.tcx.struct_span_lint_hir(lint::builtin::INVALID_HTML_TAGS, hir_id, sp, |lint| {
 120                     lint.build(msg).emit()
 121                 });
 122             };
 123
 124             let mut tags = Vec::new();
 125
 126             let p = Parser::new_ext(&dox, opts()).into_offset_iter();
 127
 128             for (event, range) in p {
 129                 match event {
 130                     Event::Html(text) => extract_tag(&mut tags, &text, range, &report_diag),
 131                     _ => {}
 132                 }
 133             }
 134
 135             for (tag, range) in
 136                 tags.iter().filter(|(t, _)| ALLOWED_UNCLOSED.iter().find(|&at| at == t).is_none())
 137             {
 138                 report_diag(&format!("unclosed HTML tag `{}`", tag), range);
 139             }
 140         }
 141
 142         self.fold_item_recur(item)
 143     }
 144 }