Skip to content

Commit

Permalink
Extend coverage attribute documentation
Browse files Browse the repository at this point in the history
This adds more details about the behavior of the `coverage` attribute,
along with some editorial changes.
  • Loading branch information
ehuss committed Dec 18, 2024
1 parent d92a412 commit b2c8b52
Showing 1 changed file with 19 additions and 4 deletions.
23 changes: 19 additions & 4 deletions src/attributes/coverage-instrumentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@ The following [attributes] are used for controlling coverage instrumentation.
r[attributes.coverage]

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

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

* `#[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.
Expand All @@ -35,10 +35,25 @@ impl S {
```

r[attributes.coverage.allowed-positions]
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.
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].

It is an error to specify the attribute on a trait function without a body.

r[attributes.coverage.trait-impl-inherit]
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.

r[attributes.coverage.duplicates]
It is an error to specify the `#[coverage]` attribute multiple times on the same item.

r[attributes.coverage.nesting]
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.
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.

[_MetaListIdents_]: ../attributes.md#meta-item-attribute-syntax
[associated functions]: ../items/associated-items.md#associated-functions-and-methods
[attribute]: ../attributes.md
[attributes]: ../attributes.md
[closures]: ../expressions/closure-expr.md
[functions]: ../items/functions.md
[implementations]: ../items/implementations.md
[modules]: ../items/modules.md
[the crate root]: ../crates-and-source-files.md

0 comments on commit b2c8b52

Please sign in to comment.