@@ -316,19 +316,86 @@ The *`deprecated` [attribute][attributes]* marks an item as deprecated.
316
316
r [attributes . diagnostics. deprecated. syntax]
317
317
The `deprecated ` attribute has several forms :
318
318
319
- - `deprecated ` --- Issues a generic message .
320
- - `deprecated = " message" ` --- Includes the given string in the deprecation message .
321
- - [MetaListNameValueStr ] syntax with two optional fields :
322
- - `since ` --- Specifies a version number when the item was deprecated . `rustc ` does not currently interpret the string , but external tools like [Clippy ] may check the validity of the value .
323
- - `note ` --- Specifies a string that should be included in the deprecation message . This is typically used to provide an explanation about the deprecation and preferred alternatives .
319
+ ```grammar ,attributes
320
+ @ root DeprecatedAttribute ->
321
+ `deprecated ` `= ` (STRING_LITERAL | RAW_STRING_LITERAL )
322
+ | `deprecated ` `(` ( MetaNameValueStr (`,` MetaNameValueStr )* `,`? )? `)`
323
+ | `deprecated `
324
+ ```
325
+
326
+ - The bare ` deprecated ` form generates a [ generic message] [ attributes.diagnostics.deprecated.generic-message ] .
327
+ - The ` deprecated = "message" ` form allows you to [ specify a message] [ attributes.diagnostics.deprecated.message ] .
328
+ - The ` deprecated() ` form allows you to [ specify optional fields] [ attributes.diagnostics.deprecated.fields ] .
329
+
330
+ r[ attributes.diagnostics.deprecated.allowed-positions]
331
+ The ` deprecated ` attribute may be applied to:
332
+ - [ items]
333
+ - [ trait items]
334
+ - [ enum variants]
335
+ - [ struct fields] (not including tuple struct fields)
336
+ - [ external block items]
337
+ - [ macro definitions]
338
+
339
+ It may not be applied to [ trait implementation items] [ trait-impl ] .
340
+
341
+ > [ !NOTE]
342
+ > ` rustc ` currently ignores ` deprecated ` in other positions, but this may be rejected in the future.
343
+
344
+ r[ attributes.diagnostics.deprecated.duplicates]
345
+ The ` deprecated ` attribute may only be specified once on an item.
346
+
347
+ r[ attributes.diagnostics.deprecated.behavior]
348
+ A warning is emitted when a deprecated item is used.
349
+
350
+ <!-- TODO: Should we be more specific about what it means to be "used"? -->
351
+
352
+ > [ !EXAMPLE]
353
+ > ``` rust
354
+ > #[deprecated = " use `bar` instead" ]
355
+ > pub fn foo () {}
356
+ >
357
+ > fn main () {
358
+ > foo (); // WARNING: deprecated
359
+ > }
360
+ > ```
361
+
362
+ > [! NOTE ]
363
+ > [Rustdoc ] highlights when an item is deprecated , including the `since ` and `note ` if available .
364
+
365
+ r [attributes . diagnostics. deprecated. generic- message ]
366
+ The [MetaWord ] form of the `deprecated ` attribute generates a generic message in the diagnostic when the item is used .
367
+
368
+ > [! EXAMPLE ]
369
+ > ```rust
370
+ > #[deprecated]
371
+ > pub fn trim_left () {}
372
+ > ```
373
+
374
+ r [attributes . diagnostics. deprecated. message]
375
+ The [MetaNameValueStr ] form of the `deprecated ` attribute includes the given message in the diagnostic when the item is used . This is typically used to provide an explanation about the deprecation and preferred alternatives .
376
+
377
+ > [! EXAMPLE ]
378
+ > ```rust
379
+ > #[deprecated = " use `trim_start` instead" ]
380
+ > pub fn trim_left () {}
381
+ > ```
382
+
383
+ r [attributes . diagnostics. deprecated. fields]
384
+ The [MetaListNameValueStr ] form of the `deprecated ` attribute allows you to specify two optional fields :
324
385
325
- r [ attributes . diagnostic . deprecated. allowed - positions ]
326
- The ` deprecated ` attribute may be applied to any [ item ], [ trait item ], [ enum variant ], [ struct field ], [ external block item ], or [ macro definition ] . It cannot be applied to [ trait implementation items ][ trait - impl ].
386
+ - ` since ` --- Specifies a version number when the item was deprecated .
387
+ - ` note ` --- Specifies a string that should be included in the deprecation message . This is equivalent to the message specified in the [ MetaNameValueStr form ][ attributes . diagnostics . deprecated . message ].
327
388
328
- <! -- NOTE : It is only rejected for trait impl items
329
- (AnnotationKind :: Prohibited ). In all other locations , it is silently ignored .
330
- Tuple struct fields are ignored .
331
- - ->
389
+ Each of these fields may only be specified at most once .
390
+
391
+ > [! EXAMPLE ]
392
+ > ```rust
393
+ > #[deprecated(since = " 1.33.0" , note = " use `trim_start` instead" )]
394
+ > pub fn trim_left () {}
395
+ > ```
396
+
397
+ > [! NOTE ]
398
+ > `rustc ` does not currently interpret the `since ` string , but external tools like [Clippy ] may check the validity of the value .
332
399
333
400
r [attributes . diagnostics. deprecated. containers]
334
401
When `deprecated ` is applied to an item containing other items , all child items inherit the deprecation attribute . This includes :
@@ -675,27 +742,28 @@ The first error message includes a somewhat confusing error message about the re
675
742
[ call expression ] : ../expressions/call-expr.md
676
743
[ crate root ] : ../crates-and-source-files.md
677
744
[ dyn trait ] : ../types/trait-object.md
678
- [ enum variant ] : ../items/enumerations.md
745
+ [ enum variants ] : ../items/enumerations.md
679
746
[ enum ] : ../items/enumerations.md
680
747
[ expression statement ] : ../statements.md#expression-statements
681
748
[ expression ] : ../expressions.md
682
- [ external block item ] : ../items/external-blocks.md
749
+ [ external block items ] : ../items/external-blocks.md
683
750
[ external blocks ] : ../items/external-blocks.md
684
751
[ functions ] : ../items/functions.md
685
752
[ impl trait ] : ../types/impl-trait.md
686
753
[ implementations ] : ../items/implementations.md
687
754
[ item ] : ../items.md
688
755
[ let statement ] : ../statements.md#let-statements
689
- [ macro definition ] : ../macros-by-example.md
756
+ [ macro definitions ] : ../macros-by-example.md
690
757
[ modules ] : ../items/modules.md
691
758
[ rustc book ] : ../../rustc/lints/index.html
692
759
[ rustc-lint-caps ] : ../../rustc/lints/levels.html#capping-lints
693
760
[ rustc-lint-cli ] : ../../rustc/lints/levels.html#via-compiler-flag
694
- [ rustdoc ] : ../../rustdoc/lints.html
695
- [ struct field ] : ../items/structs.md
761
+ [ rustdoc ] : ../../rustdoc/index.html
762
+ [ rustdoc-lints ] : ../../rustdoc/lints.html
763
+ [ struct fields ] : ../items/structs.md
696
764
[ struct ] : ../items/structs.md
697
765
[ trait declaration ] : ../items/traits.md
698
- [ trait item ] : ../items/traits.md
766
+ [ trait items ] : ../items/traits.md
699
767
[ trait-impl ] : ../items/implementations.md#trait-implementations
700
768
[ traits ] : ../items/traits.md
701
769
[ union ] : ../items/unions.md
0 commit comments