From f9f2c5cbe7651d457deb6485247b3614f36692c8 Mon Sep 17 00:00:00 2001
From: ltdk <usr@ltdk.xyz>
Date: Mon, 23 Sep 2024 19:23:27 -0400
Subject: [PATCH] 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 2b17bf45d..54247ef78 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 f3ca9173e..16cdfb6b9 100644
--- a/src/attributes.md
+++ b/src/attributes.md
@@ -289,6 +289,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/
@@ -308,6 +310,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