From 3ff8b84b266288fbf56a93b5b4acd8ec8c84c5e3 Mon Sep 17 00:00:00 2001
From: ltdk <usr@ltdk.xyz>
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 <eric@huss.org>
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 <eric@huss.org>
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 <eric@huss.org>
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 <eric@huss.org>
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 <eric@huss.org>
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 <eric@huss.org>
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 <eric@huss.org>
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