Skip to content

Commit b2c8b52

Browse files
committed
Extend coverage attribute documentation
This adds more details about the behavior of the `coverage` attribute, along with some editorial changes.
1 parent d92a412 commit b2c8b52

File tree

1 file changed

+19
-4
lines changed

1 file changed

+19
-4
lines changed

src/attributes/coverage-instrumentation.md

+19-4
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,10 @@ The following [attributes] are used for controlling coverage instrumentation.
1111
r[attributes.coverage]
1212

1313
r[attributes.coverage.intro]
14-
The *`coverage` [attribute]* indicates whether a function should instrument code coverage at all and show up in code coverage reports.
14+
The *`coverage` [attribute]* indicates whether a function should include instrumentation for code coverage and show up in code coverage reports.
1515

1616
r[attributes.coverage.syntax]
17-
There are two ways to use the coverage attribute:
17+
The attribute uses the [_MetaListIdents_] syntax to specify its behavior:
1818

1919
* `#[coverage(off)]` indicates that all functions within an item, recursively, should not be instrumented, unless specified by another attribute.
2020
* `#[coverage(on)]` (the default) indicates that all functions within an item, recursively, *should* be instrumented, unless specified by another attribute.
@@ -35,10 +35,25 @@ impl S {
3535
```
3636

3737
r[attributes.coverage.allowed-positions]
38-
The `coverage` attribute can only be controlled at the function level, but it can be applied to modules, `impl` blocks, or anything that can contain functions.
38+
The `coverage` attribute can only be controlled at the granularity of individual functions. It can be applied to [functions], [closures], [associated functions], [implementations], [modules], or [the crate root].
39+
40+
It is an error to specify the attribute on a trait function without a body.
41+
42+
r[attributes.coverage.trait-impl-inherit]
43+
When specified on a trait function, the attribute only applies to the default function body. Trait implementations do not inherit the setting from the trait definition.
44+
45+
r[attributes.coverage.duplicates]
46+
It is an error to specify the `#[coverage]` attribute multiple times on the same item.
3947

4048
r[attributes.coverage.nesting]
41-
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.
49+
Coverage attributes on more deeply nested items take priority over attributes at a higher nesting level. For example, if a crate is marked `#![coverage(off)]`, then functions inside that crate marked `#[coverage(on)]` will still have coverage.
4250

51+
[_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax
52+
[associated functions]: ../items/associated-items.md#associated-functions-and-methods
4353
[attribute]: ../attributes.md
4454
[attributes]: ../attributes.md
55+
[closures]: ../expressions/closure-expr.md
56+
[functions]: ../items/functions.md
57+
[implementations]: ../items/implementations.md
58+
[modules]: ../items/modules.md
59+
[the crate root]: ../crates-and-source-files.md

0 commit comments

Comments
 (0)