diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 91f343b8d..cf422ae3c 100644 --- a/src/SUMMARY.md +++ b/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) diff --git a/src/attributes.md b/src/attributes.md index f537e4cd2..fd7dacac8 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -329,6 +329,9 @@ The following is an index of all built-in attributes. - [`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/ [ECMA-335]: https://www.ecma-international.org/publications-and-standards/standards/ecma-335/ @@ -347,6 +350,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 diff --git a/src/attributes/coverage-instrumentation.md b/src/attributes/coverage-instrumentation.md new file mode 100644 index 000000000..8fbec0fbe --- /dev/null +++ b/src/attributes/coverage-instrumentation.md @@ -0,0 +1,59 @@ +# Coverage instrumentation attributes + +The following [attributes] are used for controlling coverage instrumentation. + +> **Note**: Coverage instrumentation is controlled in `rustc` with the [`-C instrument-coverage`] compiler flag. + +[`-C instrument-coverage`]: ../../rustc/instrument-coverage.html + +### The `coverage` attribute + +r[attributes.coverage] + +r[attributes.coverage.intro] +The *`coverage` [attribute]* indicates whether a function should include instrumentation for code coverage and show up in code coverage reports. + +r[attributes.coverage.syntax] +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. + +```rust +#[coverage(off)] +fn example() {} + +struct S; + +#[coverage(off)] +impl S { + #[coverage(on)] + fn function_with_coverage() {} + + fn function_without_coverage() {} +} +``` + +r[attributes.coverage.allowed-positions] +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] +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