Merge pull request #780 from mcarton/doc

Doc stuff

README.md

@@ -14,7 +14,7 @@ Table of contents:
 * [License](#license)
 
 ##Lints
-There are 136 lints included in this crate:
+There are 137 lints included in this crate:
 
 name                                                                                                                 | default | meaning
 ---------------------------------------------------------------------------------------------------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
@@ -43,6 +43,7 @@ name
 [cyclomatic_complexity](https://github.com/Manishearth/rust-clippy/wiki#cyclomatic_complexity)                       | warn    | finds functions that should be split up into multiple functions
 [deprecated_semver](https://github.com/Manishearth/rust-clippy/wiki#deprecated_semver)                               | warn    | `Warn` on `#[deprecated(since = "x")]` where x is not semver
 [derive_hash_xor_eq](https://github.com/Manishearth/rust-clippy/wiki#derive_hash_xor_eq)                             | warn    | deriving `Hash` but implementing `PartialEq` explicitly
+[doc_markdown](https://github.com/Manishearth/rust-clippy/wiki#doc_markdown)                                         | warn    | checks for the presence of `_`, `::` or camel-case outside ticks in documentation
 [drop_ref](https://github.com/Manishearth/rust-clippy/wiki#drop_ref)                                                 | warn    | call to `std::mem::drop` with a reference instead of an owned value, which will not call the `Drop::drop` method on the underlying value
 [duplicate_underscore_argument](https://github.com/Manishearth/rust-clippy/wiki#duplicate_underscore_argument)       | warn    | Function arguments having names which only differ by an underscore
 [empty_loop](https://github.com/Manishearth/rust-clippy/wiki#empty_loop)                                             | warn    | empty `loop {}` detected

src/bit_mask.rs

@@ -13,7 +13,7 @@ use utils::span_lint;
 /// The formula for detecting if an expression of the type  `_ <bit_op> m <cmp_op> c` (where `<bit_op>`
 /// is one of {`&`, `|`} and `<cmp_op>` is one of {`!=`, `>=`, `>`, `!=`, `>=`, `>`}) can be determined from the following table:
 ///
-/// |Comparison  |Bit-Op|Example     |is always|Formula               |
+/// |Comparison  |Bit Op|Example     |is always|Formula               |
 /// |------------|------|------------|---------|----------------------|
 /// |`==` or `!=`| `&`  |`x & 2 == 3`|`false`  |`c & m != c`          |
 /// |`<`  or `>=`| `&`  |`x & 2 < 3` |`true`   |`m < c`               |
@@ -38,7 +38,7 @@ declare_lint! {
 
 /// **What it does:** This lint checks for bit masks in comparisons which can be removed without changing the outcome. The basic structure can be seen in the following table:
 ///
-/// |Comparison|Bit-Op   |Example    |equals |
+/// |Comparison| Bit Op  |Example    |equals |
 /// |----------|---------|-----------|-------|
 /// |`>` / `<=`|`|` / `^`|`x | 2 > 3`|`x > 3`|
 /// |`<` / `>=`|`|` / `^`|`x ^ 1 < 4`|`x < 4`|
@@ -61,7 +61,7 @@ declare_lint! {
 /// is one of {`&`, '|'} and `<cmp_op>` is one of {`!=`, `>=`, `>` ,
 /// `!=`, `>=`, `>`}) can be determined from the following table:
 ///
-/// |Comparison  |Bit-Op|Example     |is always|Formula               |
+/// |Comparison  |Bit Op|Example     |is always|Formula               |
 /// |------------|------|------------|---------|----------------------|
 /// |`==` or `!=`| `&`  |`x & 2 == 3`|`false`  |`c & m != c`          |
 /// |`<`  or `>=`| `&`  |`x & 2 < 3` |`true`   |`m < c`               |
@@ -75,7 +75,7 @@ declare_lint! {
 /// There is also a lint that warns on ineffective masks that is *warn*
 /// by default.
 ///
-/// |Comparison|Bit-Op   |Example    |equals |Formula|
+/// |Comparison|Bit Op   |Example    |equals |Formula|
 /// |`>` / `<=`|`|` / `^`|`x | 2 > 3`|`x > 3`|`¹ && m <= c`|
 /// |`<` / `>=`|`|` / `^`|`x ^ 1 < 4`|`x < 4`|`¹ && m < c` |
 ///

src/consts.rs

@@ -30,7 +30,7 @@ impl From<FloatTy> for FloatWidth {
     }
 }
 
-/// a Lit_-like enum to fold constant `Expr`s into
+/// A `LitKind`-like enum to fold constant `Expr`s into.
 #[derive(Debug, Clone)]
 pub enum Constant {
     /// a String "abc"

src/copies.rs

@@ -47,7 +47,7 @@ declare_lint! {
 /// match foo {
 ///     Bar => bar(),
 ///     Quz => quz(),
-///     Baz => bar(), // <= oups
+///     Baz => bar(), // <= oops
 /// }
 /// ```
 declare_lint! {

src/derive.rs

@@ -14,7 +14,7 @@ use utils::{match_path, span_lint_and_then};
 ///
 /// **Why is this bad?** The implementation of these traits must agree (for example for use with
 /// `HashMap`) so it’s probably a bad idea to use a default-generated `Hash` implementation  with
-/// an explicitely defined `PartialEq`. In particular, the following must hold for any type:
+/// an explicitly defined `PartialEq`. In particular, the following must hold for any type:
 ///
 /// ```rust
 /// k1 == k2 ⇒ hash(k1) == hash(k2)

src/doc.rs

@@ -0,0 +1,135 @@
+use rustc::lint::*;
+use std::borrow::Cow;
+use syntax::ast;
+use syntax::codemap::Span;
+use utils::span_lint;
+
+/// **What it does:** This lint checks for the presence of `_`, `::` or camel-case words outside
+/// ticks in documentation.
+///
+/// **Why is this bad?** *Rustdoc* supports markdown formatting, `_`, `::` and camel-case probably
+/// indicates some code which should be included between ticks. `_` can also be used for empasis in
+/// markdown, this lint tries to consider that.
+///
+/// **Known problems:** Lots of bad docs won’t be fixed, what the lint checks for is limited.
+///
+/// **Examples:**
+/// ```rust
+/// /// Do something with the foo_bar parameter. See also that::other::module::foo.
+/// // ^ `foo_bar` and `that::other::module::foo` should be ticked.
+/// fn doit(foo_bar) { .. }
+/// ```
+declare_lint! {
+    pub DOC_MARKDOWN, Warn,
+    "checks for the presence of `_`, `::` or camel-case outside ticks in documentation"
+}
+
+#[derive(Copy,Clone)]
+pub struct Doc;
+
+impl LintPass for Doc {
+    fn get_lints(&self) -> LintArray {
+        lint_array![DOC_MARKDOWN]
+    }
+}
+
+impl EarlyLintPass for Doc {
+    fn check_crate(&mut self, cx: &EarlyContext, krate: &ast::Crate) {
+        check_attrs(cx, &krate.attrs, krate.span);
+    }
+
+    fn check_item(&mut self, cx: &EarlyContext, item: &ast::Item) {
+        check_attrs(cx, &item.attrs, item.span);
+    }
+}
+
+/// Collect all doc attributes. Multiple `///` are represented in different attributes. `rustdoc`
+/// has a pass to merge them, but we probably don’t want to invoke that here.
+fn collect_doc(attrs: &[ast::Attribute]) -> (Cow<str>, Option<Span>) {
+    fn doc_and_span(attr: &ast::Attribute) -> Option<(&str, Span)> {
+        if attr.node.is_sugared_doc {
+            if let ast::MetaItemKind::NameValue(_, ref doc) = attr.node.value.node {
+                if let ast::LitKind::Str(ref doc, _) = doc.node {
+                    return Some((&doc[..], attr.span));
+                }
+            }
+        }
+
+        None
+    }
+    let doc_and_span: fn(_) -> _ = doc_and_span;
+
+    let mut doc_attrs = attrs.iter().filter_map(doc_and_span);
+
+    let count = doc_attrs.clone().take(2).count();
+
+    match count {
+        0 => ("".into(), None),
+        1 => {
+            let (doc, span) = doc_attrs.next().unwrap_or_else(|| unreachable!());
+            (doc.into(), Some(span))
+        }
+        _ => (doc_attrs.map(|s| s.0).collect::<String>().into(), None),
+    }
+}
+
+pub fn check_attrs<'a>(cx: &EarlyContext, attrs: &'a [ast::Attribute], default_span: Span) {
+    let (doc, span) = collect_doc(attrs);
+    let span = span.unwrap_or(default_span);
+
+    // In markdown, `_` can be used to emphasize something, or, is a raw `_` depending on context.
+    // There really is no markdown specification that would disambiguate this properly. This is
+    // what GitHub and Rustdoc do:
+    //
+    // foo_bar test_quz    → foo_bar test_quz
+    // foo_bar_baz         → foo_bar_baz (note that the “official” spec says this should be emphasized)
+    // _foo bar_ test_quz_ → <em>foo bar</em> test_quz_
+    // \_foo bar\_         → _foo bar_
+    // (_baz_)             → (<em>baz</em>)
+    // foo _ bar _ baz     → foo _ bar _ baz
+
+    let mut in_ticks = false;
+    for word in doc.split_whitespace() {
+        let ticks = word.bytes().filter(|&b| b == b'`').count();
+
+        if ticks == 2 { // likely to be “`foo`”
+            continue;
+        } else if ticks % 2 == 1 {
+            in_ticks = !in_ticks;
+            continue; // let’s assume no one will ever write something like “`foo`_bar”
+        }
+
+        if !in_ticks {
+            check_word(cx, word, span);
+        }
+    }
+}
+
+fn check_word(cx: &EarlyContext, word: &str, span: Span) {
+    /// Checks if a string a camel-case, ie. contains at least two uppercase letter (`Clippy` is
+    /// ok) and one lower-case letter (`NASA` is ok). Plural are also excluded (`IDs` is ok).
+    fn is_camel_case(s: &str) -> bool {
+        let s = if s.ends_with('s') {
+            &s[..s.len()-1]
+        } else {
+            s
+        };
+
+        s.chars().all(char::is_alphanumeric) &&
+        s.chars().filter(|&c| c.is_uppercase()).take(2).count() > 1 &&
+        s.chars().filter(|&c| c.is_lowercase()).take(1).count() > 0
+    }
+
+    fn has_underscore(s: &str) -> bool {
+        s != "_" && !s.contains("\\_") && s.contains('_')
+    }
+
+    // Trim punctuation as in `some comment (see foo::bar).`
+    //                                                   ^^
+    // Or even as `_foo bar_` which is emphasized.
+    let word = word.trim_matches(|c: char| !c.is_alphanumeric());
+
+    if has_underscore(word) || word.contains("::") || is_camel_case(word) {
+        span_lint(cx, DOC_MARKDOWN, span, &format!("you should put `{}` between ticks in the documentation", word));
+    }
+}

src/formatting.rs

@@ -82,7 +82,7 @@ impl EarlyLintPass for Formatting {
     }
 }
 
-/// Implementation of the SUSPICIOUS_ASSIGNMENT_FORMATTING lint.
+/// Implementation of the `SUSPICIOUS_ASSIGNMENT_FORMATTING` lint.
 fn check_assign(cx: &EarlyContext, expr: &ast::Expr) {
     if let ast::ExprKind::Assign(ref lhs, ref rhs) = expr.node {
         if !differing_macro_contexts(lhs.span, rhs.span) && !in_macro(cx, lhs.span) {
@@ -108,7 +108,7 @@ fn check_assign(cx: &EarlyContext, expr: &ast::Expr) {
     }
 }
 
-/// Implementation of the SUSPICIOUS_ELSE_FORMATTING lint for weird `else if`.
+/// Implementation of the `SUSPICIOUS_ELSE_FORMATTING` lint for weird `else if`.
 fn check_else_if(cx: &EarlyContext, expr: &ast::Expr) {
     if let Some((then, &Some(ref else_))) = unsugar_if(expr) {
         if unsugar_if(else_).is_some() && !differing_macro_contexts(then.span, else_.span) && !in_macro(cx, then.span) {

src/items_after_statements.rs

@@ -32,15 +32,15 @@ declare_lint! {
     "finds blocks where an item comes after a statement"
 }
 
-pub struct ItemsAfterStatemets;
+pub struct ItemsAfterStatements;
 
-impl LintPass for ItemsAfterStatemets {
+impl LintPass for ItemsAfterStatements {
     fn get_lints(&self) -> LintArray {
         lint_array!(ITEMS_AFTER_STATEMENTS)
     }
 }
 
-impl EarlyLintPass for ItemsAfterStatemets {
+impl EarlyLintPass for ItemsAfterStatements {
     fn check_block(&mut self, cx: &EarlyContext, item: &Block) {
         if in_macro(cx, item.span) {
             return;

src/len_zero.rs

@@ -164,9 +164,9 @@ fn check_len_zero(cx: &LateContext, span: Span, name: &Name, args: &[P<Expr>], l
     }
 }
 
-/// check if this type has an is_empty method
+/// Check if this type has an `is_empty` method.
 fn has_is_empty(cx: &LateContext, expr: &Expr) -> bool {
-    /// get a ImplOrTraitItem and return true if it matches is_empty(self)
+    /// Get an `ImplOrTraitItem` and return true if it matches `is_empty(self)`.
     fn is_is_empty(cx: &LateContext, id: &ImplOrTraitItemId) -> bool {
         if let MethodTraitItemId(def_id) = *id {
             if let ty::MethodTraitItem(ref method) = cx.tcx.impl_or_trait_item(def_id) {
@@ -179,7 +179,7 @@ fn has_is_empty(cx: &LateContext, expr: &Expr) -> bool {
         }
     }
 
-    /// check the inherent impl's items for an is_empty(self) method
+    /// Check the inherent impl's items for an `is_empty(self)` method.
     fn has_is_empty_impl(cx: &LateContext, id: &DefId) -> bool {
         let impl_items = cx.tcx.impl_items.borrow();
         cx.tcx.inherent_impls.borrow().get(id).map_or(false, |ids| {

src/lib.rs

@@ -54,6 +54,7 @@ pub mod collapsible_if;
 pub mod copies;
 pub mod cyclomatic_complexity;
 pub mod derive;
+pub mod doc;
 pub mod drop_ref;
 pub mod entry;
 pub mod enum_clike;
@@ -134,7 +135,7 @@ pub fn plugin_registrar(reg: &mut Registry) {
         }
         Err((err, span)) => {
             reg.sess.struct_span_err(span, err)
-                    .span_note(span, "Clippy will use defaulf configuration")
+                    .span_note(span, "Clippy will use default configuration")
                     .emit();
             utils::conf::Conf::default()
         }
@@ -163,7 +164,7 @@ pub fn plugin_registrar(reg: &mut Registry) {
     reg.register_early_lint_pass(box precedence::Precedence);
     reg.register_late_lint_pass(box eta_reduction::EtaPass);
     reg.register_late_lint_pass(box identity_op::IdentityOp);
-    reg.register_early_lint_pass(box items_after_statements::ItemsAfterStatemets);
+    reg.register_early_lint_pass(box items_after_statements::ItemsAfterStatements);
     reg.register_late_lint_pass(box mut_mut::MutMut);
     reg.register_late_lint_pass(box mut_reference::UnnecessaryMutPassed);
     reg.register_late_lint_pass(box len_zero::LenZero);
@@ -223,6 +224,7 @@ pub fn plugin_registrar(reg: &mut Registry) {
     reg.register_late_lint_pass(box new_without_default::NewWithoutDefault);
     reg.register_late_lint_pass(box blacklisted_name::BlackListedName::new(conf.blacklisted_names));
     reg.register_late_lint_pass(box functions::Functions::new(conf.too_many_arguments_threshold));
+    reg.register_early_lint_pass(box doc::Doc);
 
     reg.register_lint_group("clippy_pedantic", vec![
         array_indexing::INDEXING_SLICING,
@@ -265,6 +267,7 @@ pub fn plugin_registrar(reg: &mut Registry) {
         cyclomatic_complexity::CYCLOMATIC_COMPLEXITY,
         derive::DERIVE_HASH_XOR_EQ,
         derive::EXPL_IMPL_CLONE_ON_COPY,
+        doc::DOC_MARKDOWN,
         drop_ref::DROP_REF,
         entry::MAP_ENTRY,
         enum_clike::ENUM_CLIKE_UNPORTABLE_VARIANT,

src/loops.rs

@@ -571,7 +571,7 @@ fn check_for_loop_explicit_counter(cx: &LateContext, arg: &Expr, body: &Expr, ex
     }
 }
 
-/// Check for the FOR_KV_MAP lint.
+/// Check for the `FOR_KV_MAP` lint.
 fn check_for_loop_over_map_kv(cx: &LateContext, pat: &Pat, arg: &Expr, body: &Expr, expr: &Expr) {
     if let PatKind::Tup(ref pat) = pat.node {
         if pat.len() == 2 {
@@ -607,7 +607,7 @@ fn check_for_loop_over_map_kv(cx: &LateContext, pat: &Pat, arg: &Expr, body: &Ex
 
 }
 
-/// Return true if the pattern is a `PatWild` or an ident prefixed with '_'.
+/// Return true if the pattern is a `PatWild` or an ident prefixed with `'_'`.
 fn pat_is_wild(pat: &PatKind, body: &Expr) -> bool {
     match *pat {
         PatKind::Wild => true,
@@ -750,8 +750,8 @@ impl<'v, 't> Visitor<'v> for VarUsedAfterLoopVisitor<'v, 't> {
 }
 
 
-/// Return true if the type of expr is one that provides IntoIterator impls
-/// for &T and &mut T, such as Vec.
+/// Return true if the type of expr is one that provides `IntoIterator` impls
+/// for `&T` and `&mut T`, such as `Vec`.
 #[cfg_attr(rustfmt, rustfmt_skip)]
 fn is_ref_iterable_type(cx: &LateContext, e: &Expr) -> bool {
     // no walk_ptrs_ty: calling iter() on a reference can make sense because it

src/matches.rs

@@ -330,7 +330,7 @@ fn check_match_ref_pats(cx: &LateContext, ex: &Expr, arms: &[Arm], source: Match
     }
 }
 
-/// Get all arms that are unbounded PatRange-s.
+/// Get all arms that are unbounded `PatRange`s.
 fn all_ranges(cx: &LateContext, arms: &[Arm]) -> Vec<SpannedRange<ConstVal>> {
     arms.iter()
         .filter_map(|arm| {

src/misc_early.rs

@@ -110,10 +110,10 @@ impl EarlyLintPass for MiscEarly {
                 let arg_name = sp_ident.node.to_string();
 
                 if arg_name.starts_with('_') {
-                    if let Some(correspondance) = registered_names.get(&arg_name[1..]) {
+                    if let Some(correspondence) = registered_names.get(&arg_name[1..]) {
                         span_lint(cx,
                                   DUPLICATE_UNDERSCORE_ARGUMENT,
-                                  *correspondance,
+                                  *correspondence,
                                   &format!("`{}` already exists, having another argument having almost the same \
                                             name makes code comprehension and documentation more difficult",
                                            arg_name[1..].to_owned()));;

src/needless_bool.rs

@@ -105,7 +105,7 @@ impl LateLintPass for BoolComparison {
                     span_lint_and_then(cx,
                                        BOOL_COMPARISON,
                                        e.span,
-                                       "equality checks against true are unnecesary",
+                                       "equality checks against true are unnecessary",
                                        |db| {
                                            db.span_suggestion(e.span, "try simplifying it as shown:", hint);
                                        });
@@ -115,7 +115,7 @@ impl LateLintPass for BoolComparison {
                     span_lint_and_then(cx,
                                        BOOL_COMPARISON,
                                        e.span,
-                                       "equality checks against true are unnecesary",
+                                       "equality checks against true are unnecessary",
                                        |db| {
                                            db.span_suggestion(e.span, "try simplifying it as shown:", hint);
                                        });

src/non_expressive_names.rs

@@ -251,7 +251,7 @@ impl EarlyLintPass for NonExpressiveNames {
     }
 }
 
-/// precondition: a_name.chars().count() < b_name.chars().count()
+/// Precondition: `a_name.chars().count() < b_name.chars().count()`.
 fn levenstein_not_1(a_name: &str, b_name: &str) -> bool {
     debug_assert!(a_name.chars().count() < b_name.chars().count());
     let mut a_chars = a_name.chars();

src/ptr_arg.rs

@@ -1,6 +1,4 @@
-//! Checks for usage of &Vec[_] and &String
-//!
-//! This lint is **warn** by default
+//! Checks for usage of  `&Vec[_]` and `&String`.
 
 use rustc::front::map::NodeItem;
 use rustc::lint::*;

src/strings.rs

@@ -1,4 +1,4 @@
-//! This LintPass catches both string addition and string addition + assignment
+//! This lint catches both string addition and string addition + assignment
 //!
 //! Note that since we have two lints where one subsumes the other, we try to
 //! disable the subsumed lint unless it has a higher level

src/utils/hir.rs

@@ -13,7 +13,7 @@ use utils::differing_macro_contexts;
 pub struct SpanlessEq<'a, 'tcx: 'a> {
     /// Context used to evaluate constant expressions.
     cx: &'a LateContext<'a, 'tcx>,
-    /// If is true, never consider as equal expressions containing fonction calls.
+    /// If is true, never consider as equal expressions containing function calls.
     ignore_fn: bool,
 }
 

src/utils/mod.rs

@@ -129,8 +129,8 @@ pub fn in_macro<T: LintContext>(cx: &T, span: Span) -> bool {
 /// Returns true if the macro that expanded the crate was outside of the current crate or was a
 /// compiler plugin.
 pub fn in_external_macro<T: LintContext>(cx: &T, span: Span) -> bool {
-    /// Invokes in_macro with the expansion info of the given span slightly heavy, try to use this
-    /// after other checks have already happened.
+    /// Invokes `in_macro` with the expansion info of the given span slightly heavy, try to use
+    /// this after other checks have already happened.
     fn in_macro_ext<T: LintContext>(cx: &T, opt_info: Option<&ExpnInfo>) -> bool {
         // no ExpnInfo = no macro
         opt_info.map_or(false, |info| {
@@ -657,7 +657,7 @@ pub fn is_direct_expn_of(cx: &LateContext, span: Span, name: &str) -> Option<Spa
     }
 }
 
-/// Returns index of character after first CamelCase component of `s`
+/// Return the index of the character after the first camel-case component of `s`.
 pub fn camel_case_until(s: &str) -> usize {
     let mut iter = s.char_indices();
     if let Some((_, first)) = iter.next() {
@@ -690,7 +690,7 @@ pub fn camel_case_until(s: &str) -> usize {
     }
 }
 
-/// Returns index of last CamelCase component of `s`.
+/// Return index of the last camel-case component of `s`.
 pub fn camel_case_from(s: &str) -> usize {
     let mut iter = s.char_indices().rev();
     if let Some((_, first)) = iter.next() {
@@ -719,7 +719,7 @@ pub fn camel_case_from(s: &str) -> usize {
     last_i
 }
 
-/// Represents a range akin to `ast::ExprKind::Range`.
+/// Represent a range akin to `ast::ExprKind::Range`.
 #[derive(Debug, Copy, Clone)]
 pub struct UnsugaredRange<'a> {
     pub start: Option<&'a Expr>,

src/zero_div_zero.rs

@@ -4,7 +4,7 @@ use rustc_front::hir::*;
 use utils::span_help_and_lint;
 
 /// `ZeroDivZeroPass` is a pass that checks for a binary expression that consists
-/// `of 0.0/0.0`, which is always NaN. It is more clear to replace instances of
+/// `of 0.0/0.0`, which is always `NaN`. It is more clear to replace instances of
 /// `0.0/0.0` with `std::f32::NaN` or `std::f64::NaN`, depending on the precision.
 pub struct ZeroDivZeroPass;
 

tests/compile-fail/bool_comparison.rs

@@ -5,7 +5,7 @@
 fn main() {
     let x = true;
     if x == true { "yes" } else { "no" };
-    //~^ ERROR equality checks against true are unnecesary
+    //~^ ERROR equality checks against true are unnecessary
     //~| HELP try simplifying it as shown:
     //~| SUGGESTION if x { "yes" } else { "no" };
     if x == false { "yes" } else { "no" };
@@ -13,7 +13,7 @@ fn main() {
     //~| HELP try simplifying it as shown:
     //~| SUGGESTION if !x { "yes" } else { "no" };
     if true == x { "yes" } else { "no" };
-    //~^ ERROR equality checks against true are unnecesary
+    //~^ ERROR equality checks against true are unnecessary
     //~| HELP try simplifying it as shown:
     //~| SUGGESTION if x { "yes" } else { "no" };
     if false == x { "yes" } else { "no" };

tests/compile-fail/doc.rs

@@ -0,0 +1,38 @@
+//! This file tests for the DOC_MARKDOWN lint
+//~^ ERROR: you should put `DOC_MARKDOWN` between ticks
+
+#![feature(plugin)]
+#![plugin(clippy)]
+
+#![deny(doc_markdown)]
+
+/// The foo_bar function does _nothing_. See also foo::bar. (note the dot there)
+/// Markdown is _weird_. I mean _really weird_.  This \_ is ok. So is `_`. But not Foo::some_fun
+/// which should be reported only once despite being __doubly bad__.
+fn foo_bar() {
+//~^ ERROR: you should put `foo_bar` between ticks
+//~| ERROR: you should put `foo::bar` between ticks
+//~| ERROR: you should put `Foo::some_fun` between ticks
+}
+
+/// That one tests multiline ticks.
+/// ```rust
+/// foo_bar FOO_BAR
+/// _foo bar_
+/// ```
+fn multiline_ticks() {
+}
+
+/// This _is a test for
+/// multiline
+/// emphasis_.
+fn test_emphasis() {
+}
+
+/// The `main` function is the entry point of the program. Here it only calls the `foo_bar` and
+/// `multiline_ticks` functions.
+fn main() {
+    foo_bar();
+    multiline_ticks();
+    test_emphasis();
+}

tests/compile-fail/methods.rs

@@ -85,8 +85,8 @@ macro_rules! opt_map {
 }
 
 /// Checks implementation of the following lints:
-/// OPTION_MAP_UNWRAP_OR
-/// OPTION_MAP_UNWRAP_OR_ELSE
+/// * `OPTION_MAP_UNWRAP_OR`
+/// * `OPTION_MAP_UNWRAP_OR_ELSE`
 fn option_methods() {
     let opt = Some(1);
 
@@ -154,7 +154,7 @@ impl IteratorFalsePositives {
     }
 }
 
-/// Checks implementation of FILTER_NEXT lint
+/// Checks implementation of `FILTER_NEXT` lint
 fn filter_next() {
     let v = vec![3, 2, 1, 0, -1, -2, -3];
 
@@ -174,7 +174,7 @@ fn filter_next() {
     let _ = foo.filter().next();
 }
 
-/// Checks implementation of SEARCH_IS_SOME lint
+/// Checks implementation of `SEARCH_IS_SOME` lint
 fn search_is_some() {
     let v = vec![3, 2, 1, 0, -1, -2, -3];
 
@@ -218,7 +218,7 @@ fn search_is_some() {
     let _ = foo.rposition().is_some();
 }
 
-/// Checks implementation of the OR_FUN_CALL lint
+/// Checks implementation of the `OR_FUN_CALL` lint
 fn or_fun_call() {
     struct Foo;
 

tests/used_underscore_binding_macro.rs

@@ -3,7 +3,7 @@
 
 extern crate rustc_serialize;
 
-/// Test that we do not lint for unused underscores in a MacroAttribute expansion
+/// Test that we do not lint for unused underscores in a `MacroAttribute` expansion
 #[deny(used_underscore_binding)]
 #[derive(RustcEncodable)]
 struct MacroAttributesTest {