Rewrite the error-code docs for coverage attributes [E0788]

Author: Zalathar

compiler/rustc_error_codes/src/error_codes/E0788.md

@@ -1,26 +1,24 @@
-A `#[coverage]` attribute was applied to something which does not show up
-in code coverage, or is too granular to be excluded from the coverage report.
+A `#[coverage(off|on)]` attribute was found in a position where it is not
+allowed.
 
-For now, this attribute can only be applied to function, method, and closure
-definitions. In the future, it may be added to statements, blocks, and
-expressions, and for the time being, using this attribute in those places
-will just emit an `unused_attributes` lint instead of this error.
+Coverage attributes can be applied to:
+- Function and method declarations that have a body, including trait methods
+  that have a default implementation.
+- Closure expressions, in situations where attributes can be applied to
+  expressions.
+- `impl` blocks (inherent or trait), and modules.
 
 Example of erroneous code:
 
 ```compile_fail,E0788
-#[coverage(off)]
-struct Foo;
-
-#[coverage(on)]
-const FOO: Foo = Foo;
+unsafe extern "C" {
+    #[coverage(off)]
+    fn foreign_fn();
+}
 ```
 
-`#[coverage(off)]` tells the compiler to not generate coverage instrumentation
-for a piece of code when the `-C instrument-coverage` flag is passed. Things
-like structs and consts are not coverable code, and thus cannot do anything
-with this attribute.
-
-If you wish to apply this attribute to all methods in an impl or module,
-manually annotate each method; it is not possible to annotate the entire impl
-with a `#[coverage]` attribute.
+When using the `-C instrument-coverage` flag, coverage attributes act as a
+hint to the compiler that it should instrument or not instrument the
+corresponding function or enclosed functions. The precise effect of applying
+a coverage attribute is not guaranteed and may change in future compiler
+versions.