3 use syntax::codemap::{Span, BytePos};
6 /// **What it does:** This lint checks for the presence of `_`, `::` or camel-case words outside
7 /// ticks in documentation.
9 /// **Why is this bad?** *Rustdoc* supports markdown formatting, `_`, `::` and camel-case probably
10 /// indicates some code which should be included between ticks. `_` can also be used for empasis in
11 /// markdown, this lint tries to consider that.
13 /// **Known problems:** Lots of bad docs won’t be fixed, what the lint checks for is limited.
17 /// /// Do something with the foo_bar parameter. See also that::other::module::foo.
18 /// // ^ `foo_bar` and `that::other::module::foo` should be ticked.
19 /// fn doit(foo_bar) { .. }
22 pub DOC_MARKDOWN, Warn,
23 "checks for the presence of `_`, `::` or camel-case outside ticks in documentation"
28 valid_idents: Vec<String>,
32 pub fn new(valid_idents: Vec<String>) -> Self {
33 Doc { valid_idents: valid_idents }
37 impl LintPass for Doc {
38 fn get_lints(&self) -> LintArray {
39 lint_array![DOC_MARKDOWN]
43 impl EarlyLintPass for Doc {
44 fn check_crate(&mut self, cx: &EarlyContext, krate: &ast::Crate) {
45 check_attrs(cx, &self.valid_idents, &krate.attrs);
48 fn check_item(&mut self, cx: &EarlyContext, item: &ast::Item) {
49 check_attrs(cx, &self.valid_idents, &item.attrs);
53 pub fn check_attrs<'a>(cx: &EarlyContext, valid_idents: &[String], attrs: &'a [ast::Attribute]) {
54 let mut in_multiline = false;
56 if attr.node.is_sugared_doc {
57 if let ast::MetaItemKind::NameValue(_, ref doc) = attr.node.value.node {
58 if let ast::LitKind::Str(ref doc, _) = doc.node {
59 // doc comments start with `///` or `//!`
60 let real_doc = &doc[3..];
61 let mut span = attr.span;
62 span.lo = span.lo + BytePos(3);
64 // check for multiline code blocks
65 if real_doc.trim_left().starts_with("```") {
66 in_multiline = !in_multiline;
69 check_doc(cx, valid_idents, real_doc, span);
77 macro_rules! jump_to {
78 // Get the next character’s first byte UTF-8 friendlyly.
79 (@next_char, $chars: expr, $len: expr) => {{
80 if let Some(&(pos, _)) = $chars.peek() {
87 // Jump to the next `$c`. If no such character is found, give up.
88 ($chars: expr, $c: expr, $len: expr) => {{
89 if $chars.find(|&(_, c)| c == $c).is_some() {
90 jump_to!(@next_char, $chars, $len)
98 #[allow(while_let_loop)] // #362
99 pub fn check_doc(cx: &EarlyContext, valid_idents: &[String], doc: &str, span: Span) {
100 // In markdown, `_` can be used to emphasize something, or, is a raw `_` depending on context.
101 // There really is no markdown specification that would disambiguate this properly. This is
102 // what GitHub and Rustdoc do:
104 // foo_bar test_quz → foo_bar test_quz
105 // foo_bar_baz → foo_bar_baz (note that the “official” spec says this should be emphasized)
106 // _foo bar_ test_quz_ → <em>foo bar</em> test_quz_
107 // \_foo bar\_ → _foo bar_
108 // (_baz_) → (<em>baz</em>)
109 // foo _ bar _ baz → foo _ bar _ baz
111 /// Character that can appear in a word
112 fn is_word_char(c: char) -> bool {
114 t if t.is_alphanumeric() => true,
120 #[allow(cast_possible_truncation)]
121 fn word_span(mut span: Span, begin: usize, end: usize) -> Span {
122 debug_assert_eq!(end as u32 as usize, end);
123 debug_assert_eq!(begin as u32 as usize, begin);
124 span.hi = span.lo + BytePos(end as u32);
125 span.lo = span.lo + BytePos(begin as u32);
129 let mut new_line = true;
131 let mut chars = doc.char_indices().peekable();
132 let mut current_word_begin = 0;
137 '#' if new_line => { // don’t warn on titles
138 current_word_begin = jump_to!(chars, '\n', len);
141 current_word_begin = jump_to!(chars, '`', len);
144 let end = jump_to!(chars, ']', len);
145 let link_text = &doc[current_word_begin + 1..end];
146 let word_span = word_span(span, current_word_begin + 1, end + 1);
150 // Trying to parse a link. Let’s ignore the link.
152 // FIXME: how does markdown handles such link?
153 // https://en.wikipedia.org/w/index.php?title=)
155 '(' => { // inline link
156 current_word_begin = jump_to!(chars, ')', len);
157 check_doc(cx, valid_idents, link_text, word_span);
159 '[' => { // reference link
160 current_word_begin = jump_to!(chars, ']', len);
161 check_doc(cx, valid_idents, link_text, word_span);
163 ':' => { // reference link
164 current_word_begin = jump_to!(chars, '\n', len);
166 _ => { // automatic reference link
167 current_word_begin = jump_to!(@next_char, chars, len);
168 check_doc(cx, valid_idents, link_text, word_span);
175 // anything that’s neither alphanumeric nor '_' is not part of an ident anyway
176 c if !c.is_alphanumeric() && c != '_' => {
177 current_word_begin = jump_to!(@next_char, chars, len);
180 let end = match chars.find(|&(_, c)| !is_word_char(c)) {
181 Some((end, _)) => end,
184 let word_span = word_span(span, current_word_begin, end);
185 check_word(cx, valid_idents, &doc[current_word_begin..end], word_span);
186 current_word_begin = jump_to!(@next_char, chars, len);
190 new_line = c == '\n' || (new_line && c.is_whitespace());
197 fn check_word(cx: &EarlyContext, valid_idents: &[String], word: &str, span: Span) {
198 /// Checks if a string a camel-case, ie. contains at least two uppercase letter (`Clippy` is
199 /// ok) and one lower-case letter (`NASA` is ok). Plural are also excluded (`IDs` is ok).
200 fn is_camel_case(s: &str) -> bool {
201 if s.starts_with(|c: char| c.is_digit(10)) {
205 let s = if s.ends_with('s') {
211 s.chars().all(char::is_alphanumeric) &&
212 s.chars().filter(|&c| c.is_uppercase()).take(2).count() > 1 &&
213 s.chars().filter(|&c| c.is_lowercase()).take(1).count() > 0
216 fn has_underscore(s: &str) -> bool {
217 s != "_" && !s.contains("\\_") && s.contains('_')
220 // Trim punctuation as in `some comment (see foo::bar).`
222 // Or even as in `_foo bar_` which is emphasized.
223 let word = word.trim_matches(|c: char| !c.is_alphanumeric());
225 if valid_idents.iter().any(|i| i == word) {
229 if has_underscore(word) || word.contains("::") || is_camel_case(word) {
233 &format!("you should put `{}` between ticks in the documentation", word));