Improve docs

clippy_lints/src/unicode.rs

@@ -5,9 +5,10 @@ use syntax::codemap::Span;
 use unicode_normalization::UnicodeNormalization;
 use utils::{snippet, span_help_and_lint};
 
-/// **What it does:** This lint checks for the unicode zero-width space in the code.
+/// **What it does:** This lint checks for the Unicode zero-width space in the code.
 ///
-/// **Why is this bad?** Having an invisible character in the code makes for all sorts of April fools, but otherwise is very much frowned upon.
+/// **Why is this bad?** Having an invisible character in the code makes for all sorts of April
+/// fools, but otherwise is very much frowned upon.
 ///
 /// **Known problems:** None
 ///
@@ -17,26 +18,34 @@ declare_lint! {
     "using a zero-width space in a string literal, which is confusing"
 }
 
-/// **What it does:** This lint checks for non-ascii characters in string literals.
+/// **What it does:** This lint checks for non-ASCII characters in string literals.
 ///
-/// **Why is this bad?** Yeah, we know, the 90's called and wanted their charset back. Even so, there still are editors and other programs out there that don't work well with unicode. So if the code is meant to be used internationally, on multiple operating systems, or has other portability requirements, activating this lint could be useful.
+/// **Why is this bad?** Yeah, we know, the 90's called and wanted their charset back. Even so,
+/// there still are editors and other programs out there that don't work well with Unicode. So if
+/// the code is meant to be used internationally, on multiple operating systems, or has other
+/// portability requirements, activating this lint could be useful.
 ///
 /// **Known problems:** None
 ///
-/// **Example:** `let x = "Hä?"`
+/// **Example:**
+/// ```rust
+/// let x = "Hä?"
+/// ```
 declare_lint! {
     pub NON_ASCII_LITERAL, Allow,
     "using any literal non-ASCII chars in a string literal; suggests \
-     using the \\u escape instead"
+     using the `\\u` escape instead"
 }
 
-/// **What it does:** This lint checks for string literals that contain unicode in a form that is not equal to its [NFC-recomposition](http://www.unicode.org/reports/tr15/#Norm_Forms).
+/// **What it does:** This lint checks for string literals that contain Unicode in a form that is
+/// not equal to its [NFC-recomposition](http://www.unicode.org/reports/tr15/#Norm_Forms).
 ///
 /// **Why is this bad?** If such a string is compared to another, the results may be surprising.
 ///
 /// **Known problems** None
 ///
-/// **Example:** You may not see it, but "à" and "à" aren't the same string. The former when escaped is actually "a\u{300}" while the latter is "\u{e0}".
+/// **Example:** You may not see it, but “à” and “à” aren't the same string. The former when
+/// escaped is actually `"a\u{300}"` while the latter is `"\u{e0}"`.
 declare_lint! {
     pub UNICODE_NOT_NFC, Allow,
     "using a unicode literal not in NFC normal form (see \