From b2c8b52c7272970d222d9d04531554355c690f66 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 18 Dec 2024 14:28:58 -0800 Subject: [PATCH] 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