diff options
| author | Guillaume Gomez <guillaume1.gomez@gmail.com> | 2025-06-07 22:22:55 +0200 |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2025-06-07 22:22:55 +0200 |
| commit | 2c8a9cccd9497d20d3f2a30c1370dd53c8f21296 (patch) | |
| tree | 5e623e4b7e5944f0e192855b647e710d6b625301 /src/doc/rustdoc | |
| parent | 2f2c8c3512e82e4315db83bbb53eb79e2c566270 (diff) | |
| parent | d96d3bed6fc14fa03b077b1b7acf493815a6ef31 (diff) | |
| download | rust-2c8a9cccd9497d20d3f2a30c1370dd53c8f21296.tar.gz rust-2c8a9cccd9497d20d3f2a30c1370dd53c8f21296.zip | |
Rollup merge of #140560 - Urgau:test_attr-module-level, r=GuillaumeGomez
Allow `#![doc(test(attr(..)))]` everywhere This PR adds the ability to specify [`#![doc(test(attr(..)))]`](https://doc.rust-lang.org/nightly/rustdoc/write-documentation/the-doc-attribute.html#testattr) ~~at module level~~ everywhere in addition to allowing it at crate-root. This is motivated by a recent PR #140323 (by ````@tgross35)```` where we have to duplicate 2 attributes to every single `f16` and `f128` doctests, by allowing `#![doc(test(attr(..)))]` at module level (and everywhere else) we can omit them entirely and just have (in both module): ```rust #![doc(test(attr(feature(cfg_target_has_reliable_f16_f128))))] #![doc(test(attr(expect(internal_features))))] ``` Those new attributes are appended to the one found at crate-root or at a previous module. Those "global" attributes are compatible with merged doctests (they already were before). Given the small addition that this is, I'm proposing to insta-stabilize it, but I can feature-gate it if preferred. Best reviewed commit by commit. r? ````@GuillaumeGomez````
Diffstat (limited to 'src/doc/rustdoc')
| -rw-r--r-- | src/doc/rustdoc/src/write-documentation/the-doc-attribute.md | 32 |
1 files changed, 23 insertions, 9 deletions
diff --git a/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md b/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md index 6ec93d1746c..65e6b417427 100644 --- a/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md +++ b/src/doc/rustdoc/src/write-documentation/the-doc-attribute.md @@ -143,15 +143,6 @@ But if you include this: it will not. -### `test(attr(...))` - -This form of the `doc` attribute allows you to add arbitrary attributes to all your doctests. For -example, if you want your doctests to fail if they have dead code, you could add this: - -```rust,no_run -#![doc(test(attr(deny(dead_code))))] -``` - ## At the item level These forms of the `#[doc]` attribute are used on individual items, to control how @@ -283,3 +274,26 @@ To get around this limitation, we just add `#[doc(alias = "lib_name_do_something on the `do_something` method and then it's all good! Users can now look for `lib_name_do_something` in our crate directly and find `Obj::do_something`. + +### `test(attr(...))` + +This form of the `doc` attribute allows you to add arbitrary attributes to all your doctests. For +example, if you want your doctests to fail if they have dead code, you could add this: + +```rust,no_run +#![doc(test(attr(deny(dead_code))))] + +mod my_mod { + #![doc(test(attr(allow(dead_code))))] // but allow `dead_code` for this module +} +``` + +`test(attr(..))` attributes are appended to the parent module's, they do not replace the current +list of attributes. In the previous example, both attributes would be present: + +```rust,no_run +// For every doctest in `my_mod` + +#![deny(dead_code)] // from the crate-root +#![allow(dead_code)] // from `my_mod` +``` |
