From 3ff8b84b266288fbf56a93b5b4acd8ec8c84c5e3 Mon Sep 17 00:00:00 2001 From: ltdk Date: Mon, 23 Sep 2024 19:23:27 -0400 Subject: [PATCH 1/8] Mention coverage attribute --- src/SUMMARY.md | 1 + src/attributes.md | 3 +++ src/attributes/coverage-instrumentation.md | 25 ++++++++++++++++++++++ 3 files changed, 29 insertions(+) create mode 100644 src/attributes/coverage-instrumentation.md 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..376ed392c 100644 --- a/src/attributes.md +++ b/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 diff --git a/src/attributes/coverage-instrumentation.md b/src/attributes/coverage-instrumentation.md new file mode 100644 index 000000000..bdbbce747 --- /dev/null +++ b/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 From 081372c58fec436d19245449c0f9e4b360b1ff45 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2024 13:18:34 -0800 Subject: [PATCH 2/8] Unwrap text --- src/attributes/coverage-instrumentation.md | 18 +++++------------- 1 file changed, 5 insertions(+), 13 deletions(-) diff --git a/src/attributes/coverage-instrumentation.md b/src/attributes/coverage-instrumentation.md index bdbbce747..e922a184a 100644 --- a/src/attributes/coverage-instrumentation.md +++ b/src/attributes/coverage-instrumentation.md @@ -1,25 +1,17 @@ # Coverage instrumentation attributes -The following [attributes] are used for controlling coverage instrumentation, -which can be enabled with the `-C instrument-coverage` compiler flag. +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. +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. +* `#[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. +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 From f71cbc6fa0694e7547eba941a3f59ec302d4976c Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2024 13:29:18 -0800 Subject: [PATCH 3/8] Add rule annotations --- src/attributes/coverage-instrumentation.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/attributes/coverage-instrumentation.md b/src/attributes/coverage-instrumentation.md index e922a184a..7964500b0 100644 --- a/src/attributes/coverage-instrumentation.md +++ b/src/attributes/coverage-instrumentation.md @@ -4,13 +4,21 @@ The following [attributes] are used for controlling coverage instrumentation, wh ### 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. +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. + +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. + +r[attributes.coverage.syntax] 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. +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. [attribute]: ../attributes.md From 6847eb739077d2675a02257db84eb24c5a6b7a0a Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2024 14:19:43 -0800 Subject: [PATCH 4/8] Fix formatting in builtin attribute list --- src/attributes.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/attributes.md b/src/attributes.md index 376ed392c..fd7dacac8 100644 --- a/src/attributes.md +++ b/src/attributes.md @@ -328,8 +328,9 @@ 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 + - [`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/ From 73b4272cc04682edb7e0491e647a8c97a8625961 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2024 14:21:09 -0800 Subject: [PATCH 5/8] Move mention of `rustc` to a side note and link to the rustc documentation. --- src/attributes/coverage-instrumentation.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/attributes/coverage-instrumentation.md b/src/attributes/coverage-instrumentation.md index 7964500b0..9490d8309 100644 --- a/src/attributes/coverage-instrumentation.md +++ b/src/attributes/coverage-instrumentation.md @@ -1,6 +1,10 @@ # Coverage instrumentation attributes -The following [attributes] are used for controlling coverage instrumentation, which can be enabled with the `-C instrument-coverage` compiler flag. +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 From 6fe508fdf06de729c1013bc04a0d8dd0251b25f1 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2024 14:23:38 -0800 Subject: [PATCH 6/8] Move attributes.coverage.allowed-positions below syntax Toss up which makes more sense in sequence, but this felt a little better to me. --- src/attributes/coverage-instrumentation.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/attributes/coverage-instrumentation.md b/src/attributes/coverage-instrumentation.md index 9490d8309..1b98bfd20 100644 --- a/src/attributes/coverage-instrumentation.md +++ b/src/attributes/coverage-instrumentation.md @@ -13,15 +13,15 @@ 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. -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. - r[attributes.coverage.syntax] 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. +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. + 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. From d92a412c4f2344dc6047b0e34dc97228a70491e5 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2024 14:24:26 -0800 Subject: [PATCH 7/8] Add an example showing the attribute in use. --- src/attributes/coverage-instrumentation.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/attributes/coverage-instrumentation.md b/src/attributes/coverage-instrumentation.md index 1b98bfd20..23795f551 100644 --- a/src/attributes/coverage-instrumentation.md +++ b/src/attributes/coverage-instrumentation.md @@ -19,6 +19,21 @@ 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. +```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 function level, but it can be applied to modules, `impl` blocks, or anything that can contain functions. From b2c8b52c7272970d222d9d04531554355c690f66 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2024 14:28:58 -0800 Subject: [PATCH 8/8] Extend coverage attribute documentation This adds more details about the behavior of the `coverage` attribute, along with some editorial changes. --- src/attributes/coverage-instrumentation.md | 23 ++++++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/src/attributes/coverage-instrumentation.md b/src/attributes/coverage-instrumentation.md index 23795f551..8fbec0fbe 100644 --- a/src/attributes/coverage-instrumentation.md +++ b/src/attributes/coverage-instrumentation.md @@ -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. @@ -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