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 pulldown_cmark::{Event, Parser};
   7 use rustc_hir::hir_id::HirId;
   8 use rustc_session::lint;
   9 use rustc_span::Span;
  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     let mut coll = InvalidHtmlTagsLinter::new(cx);
  29
  30     coll.fold_crate(krate)
  31 }
  32
  33 const ALLOWED_UNCLOSED: &[&str] = &[
  34     "area", "base", "br", "col", "embed", "hr", "img", "input", "keygen", "link", "meta", "param",
  35     "source", "track", "wbr",
  36 ];
  37
  38 fn drop_tag(
  39     cx: &DocContext<'_>,
  40     tags: &mut Vec<String>,
  41     tag_name: String,
  42     hir_id: HirId,
  43     sp: Span,
  44 ) {
  45     if let Some(pos) = tags.iter().position(|t| *t == tag_name) {
  46         for _ in pos + 1..tags.len() {
  47             if ALLOWED_UNCLOSED.iter().find(|&at| at == &tags[pos + 1]).is_some() {
  48                 continue;
  49             }
  50             // `tags` is used as a queue, meaning that everything after `pos` is included inside it.
  51             // So `<h2><h3></h2>` will look like `["h2", "h3"]`. So when closing `h2`, we will still
  52             // have `h3`, meaning the tag wasn't closed as it should have.
  53             cx.tcx.struct_span_lint_hir(lint::builtin::INVALID_HTML_TAGS, hir_id, sp, |lint| {
  54                 lint.build(&format!("unclosed HTML tag `{}`", tags[pos + 1])).emit()
  55             });
  56             tags.remove(pos + 1);
  57         }
  58         tags.remove(pos);
  59     } else {
  60         // It can happen for example in this case: `<h2></script></h2>` (the `h2` tag isn't required
  61         // but it helps for the visualization).
  62         cx.tcx.struct_span_lint_hir(lint::builtin::INVALID_HTML_TAGS, hir_id, sp, |lint| {
  63             lint.build(&format!("unopened HTML tag `{}`", tag_name)).emit()
  64         });
  65     }
  66 }
  67
  68 fn extract_tag(cx: &DocContext<'_>, tags: &mut Vec<String>, text: &str, hir_id: HirId, sp: Span) {
  69     let mut iter = text.chars().peekable();
  70
  71     while let Some(c) = iter.next() {
  72         if c == '<' {
  73             let mut tag_name = String::new();
  74             let mut is_closing = false;
  75             while let Some(&c) = iter.peek() {
  76                 // </tag>
  77                 if c == '/' && tag_name.is_empty() {
  78                     is_closing = true;
  79                 } else if c.is_ascii_alphanumeric() && !c.is_ascii_uppercase() {
  80                     tag_name.push(c);
  81                 } else {
  82                     break;
  83                 }
  84                 iter.next();
  85             }
  86             if tag_name.is_empty() {
  87                 // Not an HTML tag presumably...
  88                 continue;
  89             }
  90             if is_closing {
  91                 drop_tag(cx, tags, tag_name, hir_id, sp);
  92             } else {
  93                 tags.push(tag_name);
  94             }
  95         }
  96     }
  97 }
  98
  99 impl<'a, 'tcx> DocFolder for InvalidHtmlTagsLinter<'a, 'tcx> {
 100     fn fold_item(&mut self, item: Item) -> Option<Item> {
 101         let hir_id = match self.cx.as_local_hir_id(item.def_id) {
 102             Some(hir_id) => hir_id,
 103             None => {
 104                 // If non-local, no need to check anything.
 105                 return None;
 106             }
 107         };
 108         let dox = item.attrs.collapsed_doc_value().unwrap_or_default();
 109         if !dox.is_empty() {
 110             let sp = span_of_attrs(&item.attrs).unwrap_or(item.source.span());
 111             let mut tags = Vec::new();
 112
 113             let p = Parser::new_ext(&dox, opts());
 114
 115             for event in p {
 116                 match event {
 117                     Event::Html(text) => extract_tag(self.cx, &mut tags, &text, hir_id, sp),
 118                     _ => {}
 119                 }
 120             }
 121
 122             for tag in tags.iter().filter(|t| ALLOWED_UNCLOSED.iter().find(|at| at == t).is_none())
 123             {
 124                 self.cx.tcx.struct_span_lint_hir(
 125                     lint::builtin::INVALID_HTML_TAGS,
 126                     hir_id,
 127                     sp,
 128                     |lint| lint.build(&format!("unclosed HTML tag `{}`", tag)).emit(),
 129                 );
 130             }
 131         }
 132
 133         self.fold_item_recur(item)
 134     }
 135 }