Add comment annotations (#14414)

Fix missing comment annotations in the clippy book

changelog: none

Author: flip1995

book/src/development/adding_lints.md

@@ -99,19 +99,22 @@ struct A;
 impl A {
     pub fn fo(&self) {}
     pub fn foo(&self) {}
+    //~^ foo_functions
     pub fn food(&self) {}
 }
 
 // Default trait methods
 trait B {
     fn fo(&self) {}
     fn foo(&self) {}
+    //~^ foo_functions
     fn food(&self) {}
 }
 
 // Plain functions
 fn fo() {}
 fn foo() {}
+//~^ foo_functions
 fn food() {}
 
 fn main() {
@@ -122,17 +125,20 @@ fn main() {
 }
 ```
 
-Now we can run the test with `TESTNAME=foo_functions cargo uibless`, currently
-this test is meaningless though.
+Note that we are adding comment annotations with the name of our lint to mark
+lines where we expect an error. Once we have implemented our lint we can run
+`TESTNAME=foo_functions cargo uibless` to generate the `.stderr` file. If our
+lint makes use of structured suggestions then this command will also generate
+the corresponding `.fixed` file.
 
 While we are working on implementing our lint, we can keep running the UI test.
 That allows us to check if the output is turning into what we want by checking the
 `.stderr` file that gets updated on every test run.
 
-Running `TESTNAME=foo_functions cargo uitest` should pass on its own. When we
-commit our lint, we need to commit the generated `.stderr` files, too. In
-general, you should only commit files changed by `cargo bless` for the
-specific lint you are creating/editing.
+Once we have implemented our lint running `TESTNAME=foo_functions cargo uitest`
+should pass on its own. When we commit our lint, we need to commit the generated
+ `.stderr` and if applicable `.fixed` files, too. In general, you should only
+ commit files changed by `cargo bless` for the specific lint you are creating/editing.
 
 > _Note:_ you can run multiple test files by specifying a comma separated list:
 > `TESTNAME=foo_functions,test2,test3`.

book/src/development/writing_tests.md

@@ -41,20 +41,23 @@ Update the file with some examples to get started:
 struct A;
 impl A {
     pub fn fo(&self) {}
-    pub fn foo(&self) {} //~ ERROR: function called "foo"
+    pub fn foo(&self) {}
+    //~^ foo_functions
     pub fn food(&self) {}
 }
 
 // Default trait methods
 trait B {
     fn fo(&self) {}
-    fn foo(&self) {} //~ ERROR: function called "foo"
+    fn foo(&self) {}
+    //~^ foo_functions
     fn food(&self) {}
 }
 
 // Plain functions
 fn fo() {}
-fn foo() {} //~ ERROR: function called "foo"
+fn foo() {}
+//~^ foo_functions
 fn food() {}
 
 fn main() {
@@ -66,19 +69,38 @@ fn main() {
 ```
 
 Without actual lint logic to emit the lint when we see a `foo` function name,
-this test will just pass, because no lint will be emitted. However, we can now
-run the test with the following command:
+this test will fail, because we expect errors at lines marked with
+`//~^ foo_functions`. However, we can now run the test with the following command:
 
 ```sh
 $ TESTNAME=foo_functions cargo uitest
 ```
 
-Clippy will compile and it will conclude with an `ok` for the tests:
+Clippy will compile and it will fail complaining it didn't receive any errors:
 
 ```
 ...Clippy warnings and test outputs...
-test compile_test ... ok
-test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.48s
+error: diagnostic code `clippy::foo_functions` not found on line 8
+ --> tests/ui/foo_functions.rs:9:10
+  |
+9 |     //~^ foo_functions
+  |          ^^^^^^^^^^^^^ expected because of this pattern
+  |
+
+error: diagnostic code `clippy::foo_functions` not found on line 16
+  --> tests/ui/foo_functions.rs:17:10
+   |
+17 |     //~^ foo_functions
+   |          ^^^^^^^^^^^^^ expected because of this pattern
+   |
+
+error: diagnostic code `clippy::foo_functions` not found on line 23
+  --> tests/ui/foo_functions.rs:24:6
+   |
+24 | //~^ foo_functions
+   |      ^^^^^^^^^^^^^ expected because of this pattern
+   |
+
 ```
 
 This is normal. After all, we wrote a bunch of Rust code but we haven't really