Mention coverage attribute

Author: clarfonthey

src/SUMMARY.md

@@ -45,6 +45,7 @@
     - [Limits](attributes/limits.md)
     - [Type System](attributes/type_system.md)
     - [Debugger](attributes/debugger.md)
+    - [Coverage instrumentation](attributes/coverage-instrumentation.md)
 
 - [Statements and expressions](statements-and-expressions.md)
     - [Statements](statements.md)

src/attributes.md

@@ -328,6 +328,8 @@ The following is an index of all built-in attributes.
 - Debugger
   - [`debugger_visualizer`] --- Embeds a file that specifies debugger output for a type.
   - [`collapse_debuginfo`] --- Controls how macro invocations are encoded in debuginfo.
+- Coverage Instrumentation
+  - [`coverage`] --- Controls how code coverage is instrumented
 
 [Doc comments]: comments.md#doc-comments
 [ECMA-334]: https://www.ecma-international.org/publications-and-standards/standards/ecma-334/
@@ -347,6 +349,7 @@ The following is an index of all built-in attributes.
 [`cfg`]: conditional-compilation.md#the-cfg-attribute
 [`cold`]: attributes/codegen.md#the-cold-attribute
 [`collapse_debuginfo`]: attributes/debugger.md#the-collapse_debuginfo-attribute
+[`coverage`]: attributes/coverage-instrumentation.md#the-coverage-attribute
 [`crate_name`]: crates-and-source-files.md#the-crate_name-attribute
 [`crate_type`]: linkage.md
 [`debugger_visualizer`]: attributes/debugger.md#the-debugger_visualizer-attribute

src/attributes/coverage-instrumentation.md

@@ -0,0 +1,25 @@
+# Coverage instrumentation attributes
+
+The following [attributes] are used for controlling coverage instrumentation,
+which can be enabled with the `-C instrument-coverage` compiler flag.
+
+### The `coverage` attribute
+
+The *`coverage` [attribute]* indicates whether a function should instrument code
+coverage at all and show up in code coverage reports. It can only be controlled
+at the function level, but it can be applied to modules, `impl` blocks, or
+anything that can contain functions.
+
+There are two ways to use the coverage attribute:
+
+* `#[coverage(off)]` indicates that all functions within an item, recursively,
+  should not be instrumented, unless specified by another attribute.
+* `#[coverage(on)]` (the default) indicates that all functions within an item,
+  recursively, *should* be instrumented, unless specified by another attribute.
+
+More-specific attributes always take priority over less-specific ones, e.g.
+if a crate is marked `#![coverage(off)]`, then functions inside that crate
+marked `#[coverage(on)]` will still have coverage.
+
+[attribute]: ../attributes.md
+[attributes]: ../attributes.md