Fix bugs and improve documentation

Some bugs and some documentation is unrelated to the Applicability change, but
these bugs were serious and the documentation was kind of required to
understand what's going on.

Author: flip1995

clippy_lints/src/else_if_without_else.rs

@@ -12,10 +12,9 @@
 
 use crate::rustc::lint::{EarlyContext, EarlyLintPass, LintArray, LintPass, in_external_macro, LintContext};
 use crate::rustc::{declare_tool_lint, lint_array};
-use crate::rustc_errors::Applicability;
 use crate::syntax::ast::*;
 
-use crate::utils::span_lint_and_sugg;
+use crate::utils::span_help_and_lint;
 
 /// **What it does:** Checks for usage of if expressions with an `else if` branch,
 /// but without a final `else` branch.
@@ -67,14 +66,12 @@ impl EarlyLintPass for ElseIfWithoutElse {
 
         while let ExprKind::If(_, _, Some(ref els)) = item.node {
             if let ExprKind::If(_, _, None) = els.node {
-                span_lint_and_sugg(
+                span_help_and_lint(
                     cx,
                     ELSE_IF_WITHOUT_ELSE,
                     els.span,
                     "if expression with an `else if`, but without a final `else`",
                     "add an `else` block here",
-                    String::new(),
-                    Applicability::Unspecified,
                 );
             }
 

clippy_lints/src/methods/mod.rs

@@ -2046,10 +2046,10 @@ fn lint_chars_next_cmp<'a, 'tcx>(cx: &LateContext<'a, 'tcx>, info: &BinaryExprIn
 
 /// Checks for the `CHARS_LAST_CMP` lint.
 fn lint_chars_last_cmp<'a, 'tcx>(cx: &LateContext<'a, 'tcx>, info: &BinaryExprInfo<'_>) -> bool {
-    if lint_chars_cmp(cx, info, &["chars", "last"], CHARS_NEXT_CMP, "ends_with") {
+    if lint_chars_cmp(cx, info, &["chars", "last"], CHARS_LAST_CMP, "ends_with") {
         true
     } else {
-        lint_chars_cmp(cx, info, &["chars", "next_back"], CHARS_NEXT_CMP, "ends_with")
+        lint_chars_cmp(cx, info, &["chars", "next_back"], CHARS_LAST_CMP, "ends_with")
     }
 }
 

clippy_lints/src/utils/mod.rs

@@ -384,24 +384,25 @@ pub fn snippet<'a, 'b, T: LintContext<'b>>(cx: &T, span: Span, default: &'a str)
     snippet_opt(cx, span).map_or_else(|| Cow::Borrowed(default), From::from)
 }
 
+/// Same as `snippet`, but it adapts the applicability level by following rules:
+///
+/// - Applicability level `Unspecified` will never be changed.
+/// - If the span is inside a macro, change the applicability level to `MaybeIncorrect`.
+/// - If the default value is used and the applicability level is `MachineApplicable`, change it to
+/// `HasPlaceholders`
 pub fn snippet_with_applicability<'a, 'b, T: LintContext<'b>>(
     cx: &T,
     span: Span,
     default: &'a str,
     applicability: &mut Applicability,
 ) -> Cow<'a, str> {
+    if *applicability != Applicability::Unspecified && in_macro(span) {
+        *applicability = Applicability::MaybeIncorrect;
+    }
     snippet_opt(cx, span).map_or_else(
         || {
-            // If the applicability is already `HasPlaceholders` or `MaybeIncorrect` don't change it.
-            // Also `Unspecified` shouldn't be changed
-            // Only if the applicability level is originally `MachineApplicable` and the default value
-            // has to be used change it to `HasPlaceholders`
             if *applicability == Applicability::MachineApplicable {
-                if in_macro(span) {
-                    *applicability = Applicability::MaybeIncorrect;
-                } else {
-                    *applicability = Applicability::HasPlaceholders;
-                }
+                *applicability = Applicability::HasPlaceholders;
             }
             Cow::Borrowed(default)
         },
@@ -435,6 +436,18 @@ pub fn snippet_block<'a, 'b, T: LintContext<'b>>(cx: &T, span: Span, default: &'
     trim_multiline(snip, true)
 }
 
+/// Same as `snippet_block`, but adapts the applicability level by the rules of
+/// `snippet_with_applicabiliy`.
+pub fn snippet_block_with_applicability<'a, 'b, T: LintContext<'b>>(
+    cx: &T,
+    span: Span,
+    default: &'a str,
+    applicability: &mut Applicability,
+) -> Cow<'a, str> {
+    let snip = snippet_with_applicability(cx, span, default, applicability);
+    trim_multiline(snip, true)
+}
+
 /// Returns a new Span that covers the full last line of the given Span
 pub fn last_line_of_span<'a, T: LintContext<'a>>(cx: &T, span: Span) -> Span {
     let source_map_and_line = cx.sess().source_map().lookup_line(span.lo()).unwrap();

clippy_lints/src/utils/sugg.rs

@@ -24,7 +24,7 @@ use crate::syntax::parse::token;
 use crate::syntax::print::pprust::token_to_string;
 use crate::syntax::util::parser::AssocOp;
 use crate::syntax::ast;
-use crate::utils::{higher, snippet, snippet_opt};
+use crate::utils::{higher, in_macro, snippet, snippet_opt};
 use crate::syntax_pos::{BytePos, Pos};
 use crate::rustc_errors::Applicability;
 
@@ -96,7 +96,21 @@ impl<'a> Sugg<'a> {
         Self::hir_opt(cx, expr).unwrap_or_else(|| Sugg::NonParen(Cow::Borrowed(default)))
     }
 
-    pub fn hir_with_applicability(cx: &LateContext<'_, '_>, expr: &hir::Expr, default: &'a str, applicability: &mut Applicability) -> Self {
+    /// Same as `hir`, but it adapts the applicability level by following rules:
+    ///
+    /// - Applicability level `Unspecified` will never be changed.
+    /// - If the span is inside a macro, change the applicability level to `MaybeIncorrect`.
+    /// - If the default value is used and the applicability level is `MachineApplicable`, change it to
+    /// `HasPlaceholders`
+    pub fn hir_with_applicability(
+        cx: &LateContext<'_, '_>,
+        expr: &hir::Expr,
+        default: &'a str,
+        applicability: &mut Applicability,
+    ) -> Self {
+        if *applicability != Applicability::Unspecified && in_macro(expr.span) {
+            *applicability = Applicability::MaybeIncorrect;
+        }
         Self::hir_opt(cx, expr).unwrap_or_else(|| {
             if *applicability == Applicability::MachineApplicable {
                 *applicability = Applicability::HasPlaceholders;

clippy_lints/src/write.rs

@@ -258,6 +258,20 @@ impl EarlyLintPass for Pass {
     }
 }
 
+/// Checks the arguments of `print[ln]!` and `write[ln]!` calls. It will return a tuple of two
+/// options. The first part of the tuple is format_str of the macros. The secund part of the tuple
+/// is in the `write[ln]!` case the expression the format_str should be written to.
+///
+/// Example:
+///
+/// Calling this function on
+/// ```rust,ignore
+/// writeln!(buf, "string to write: {}", something)
+/// ```
+/// will return
+/// ```rust,ignore
+/// (Some("string to write: {}"), Some(buf))
+/// ```
 fn check_tts<'a>(cx: &EarlyContext<'a>, tts: &ThinTokenStream, is_write: bool) -> (Option<String>, Option<Expr>) {
     use crate::fmt_macros::*;
     let tts = TokenStream::from(tts.clone());