General fixes based on reviews

Author: blyxyas

book/src/development/emitting_lints.md

@@ -9,11 +9,8 @@ Note that we will not go into concrete implementation of a lint logic in this
 chapter. We will go into details in later chapters as well as in two examples
 of real Clippy lints.
 
-In this chapter, we'll see an example of an imaginary `LateLintPass` lint named `bar_expressions`, that checks for
-expresions named `bar`.
-
-To emit a lint with `LateLintPass`, we must implement it for the lint that we have
-declared. Take a look at the [LateLintPass][late_lint_pass] documentation, which
+To emit a lint, we must implement a pass (see [Lint Passes](lint_passes.md)) for the lint that we have
+declared. In this example we'll implement a "late" lint, so take a look at the [LateLintPass][late_lint_pass] documentation, which
 provides an abundance of methods that we can implement for our lint.
 
 ```rust
@@ -23,48 +20,39 @@ pub trait LateLintPass<'tcx>: LintPass {
 ```
 
 By far the most common method used for Clippy lints is [`check_expr` method][late_check_expr],
-this is likely because Rust is an expression language and, more often than not,
+this is because Rust is an expression language and, more often than not,
 the lint we want to work on must examine expressions.
 
 > _Note:_ If you don't fully understand what expressions are in Rust,
 > take a look at the official documentation on [expressions][rust_expressions]
 
 Other common ones include the [`check_fn` method][late_check_fn] and the
-[`check_item` method][late_check_item]. We choose to implement whichever trait
-method based on what we need for the lint at hand.
-
-### Implement Trait Method
-
-Assume that we have added and defined a `bar_expressions` lint, we could write
-down a skeleton for this lint as the following:
-
-```rust
-impl<'tcx> LateLintPass<'tcx> for BarExpressions {
-    fn check_expr(&mut self, cx: &LateContext<'tcx>, expr: &'tcx Expr<'_>)  {}
-}
-```
+[`check_item` method][late_check_item].
 
 ### Emitting a lint
 
 Inside the trait method that we implement, we can write down the lint logic
-and the emit the lint with suggestions.
+and emit the lint with suggestions.
 
 Clippy's [diagnostics] provides quite a few diagnostic functions that we can
 use to emit lints. Take a look at the documentation to pick one that suits
 your lint's needs the best. Some common ones you will encounter in the Clippy
 repository includes:
 
-- [span_lint_and_help]: emits a lint and provides a helpful message
-- [span_lint_and_sugg]: emits a lint and provides a suggestion to fix the code
+- [`span_lint`]: Emits a lint without providing any other information
+- [`span_lint_and_note`]: Emits a lint and adds a note
+- [`span_lint_and_help`]: Emits a lint and provides a helpful message
+- [`span_lint_and_sugg`]: Emits a lint and provides a suggestion to fix the code
+- [`span_lint_and_then`]: Like `span_lint`, but allows for a lot of output customization.
 
 ```rust
-impl<'tcx> LateLintPass<'tcx> for BarExpressions {
+impl<'tcx> LateLintPass<'tcx> for LintName {
     fn check_expr(&mut self, cx: &LateContext<'tcx>, expr: &'tcx Expr<'_>)  {
-        // Imagine that `some_bar_expr_logic` checks for requirements for emitting the lint
-        if some_bar_expr_logic(expr) {
+        // Imagine that `some_lint_expr_logic` checks for requirements for emitting the lint
+        if some_lint_expr_logic(expr) {
             span_lint_and_help(
                 cx, // < The context
-                FOO_FUNCTIONS, // < The name of the lint in ALL CAPS
+                LINT_NAME, // < The name of the lint in ALL CAPS
                 expr.span, // < The span to lint
                 "message on why the lint is emitted",
                 None, // < An optional help span (to highlight something in the lint)
@@ -75,17 +63,16 @@ impl<'tcx> LateLintPass<'tcx> for BarExpressions {
 }
 ```
 
-> Note: According to [the rustc-dev-guide], the message should be matter of fact and avoid
-> capitalization and periods, unless multiple sentences are needed. When code or
-> an identifier must appear in a message or label, it should be surrounded with
-> single grave accents (\`).
+> Note: The message should be matter of fact and avoid
+> capitalization and punctuation. If multiple sentences are needed, the messages should probably be split up into an
+> error + a help / note / suggestion message.
 
 ## Suggestions: Automatic fixes
 
-Some lints know what to change in order to fix the lint. A real world example, the lint
-[`range_plus`][range_plus_one] lints for ranges where the user wrote `x..y + 1` instead of using an
-[inclusive range][inclusive_range] (`x..=1`). The fix to this lint would be just changing your `x..y + 1` expression
-to `x..=y`, **this is where suggestions come in**.
+Some lints know what to change in order to fix the code. For example, the lint
+[`range_plus`][range_plus_one] warns for ranges where the user wrote `x..y + 1` instead of using an
+[inclusive range][inclusive_range] (`x..=1`). The fix to this code would be changing the `x..y + 1` expression
+to `x..=y`. **This is where suggestions come in**.
 
 A suggestion is a change that the lint provides to fix the issue it is linting.
 The output looks something like this (from the example earlier):
@@ -102,21 +89,21 @@ LL |     for _ in 1..1 + 1 {}
 [Applicability][applicability].
 
 Applicability indicates confidence in the correctness of the suggestion, some are always right
-(`Applicability::MachineApplicable`), but we use `Applicability::MaybeIncorrect` and other when talking about a lint
+(`Applicability::MachineApplicable`), but we use `Applicability::MaybeIncorrect` and others when talking about a lint
 that may be incorrect.
 
 ---
 
-The same lint (`foo_functions`) but that emits a suggestion would be something like this:
+The same lint `LINT_NAME` but that emits a suggestion would be something like this:
 
 ```rust
-impl<'tcx> LateLintPass<'tcx> for BarExpressions {
+impl<'tcx> LateLintPass<'tcx> for LintName {
     fn check_expr(&mut self, cx: &LateContext<'tcx>, expr: &'tcx Expr<'_>)  {
-        // Imagine that `some_bar_expr_logic` checks for requirements for emitting the lint
-        if some_bar_expr_logic(expr) {
+        // Imagine that `some_lint_expr_logic` checks for requirements for emitting the lint
+        if some_lint_expr_logic(expr) {
             span_lint_and_sugg( // < Note this change
                 cx,
-                BAR_EXPRESSIONS,
+                LINT_NAME,
                 span,
                 "message on why the lint is emitted",
                 "use",
@@ -171,8 +158,8 @@ error: constant division of 0.0 with 0.0 will always result in NaN
 
 ---
 
-Suggestions are the most helpful, they are direct changes to the source code in order to fix the error. The magic
-in suggestions is that tools like rustfix can detect them and automatically fix your code.
+Suggestions are the most helpful, they are changes to the source code to fix the error. The magic
+in suggestions is that tools like `rustfix` can detect them and automatically fix your code.
 
 Example:
 
@@ -208,8 +195,11 @@ cover in the next chapters.
 [late_check_item]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.LateLintPass.html#method.check_item
 [late_lint_pass]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint/trait.LateLintPass.html
 [rust_expressions]: https://doc.rust-lang.org/reference/expressions.html
-[span_lint_and_help]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/diagnostics/fn.span_lint_and_help.html
-[span_lint_and_sugg]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/diagnostics/fn.span_lint_and_sugg.html
+[`span_lint`]: https://doc.rust-lang.org/beta/nightly-rustc/clippy_utils/diagnostics/fn.span_lint.html
+[`span_lint_and_note`]: https://doc.rust-lang.org/beta/nightly-rustc/clippy_utils/diagnostics/fn.span_lint_and_note.html
+[`span_lint_and_help`]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/diagnostics/fn.span_lint_and_help.html
+[`span_lint_and_sugg`]: https://doc.rust-lang.org/nightly/nightly-rustc/clippy_utils/diagnostics/fn.span_lint_and_sugg.html
+[`span_lint_and_then`]: https://doc.rust-lang.org/beta/nightly-rustc/clippy_utils/diagnostics/fn.span_lint_and_then.html
 [the rustc-dev-guide]: https://rustc-dev-guide.rust-lang.org/diagnostics.html
 [range_plus_one]: https://rust-lang.github.io/rust-clippy/master/index.html#range_plus_one
 [inclusive_range]: https://doc.rust-lang.org/std/ops/struct.RangeInclusive.html