src/doc/rust-by-example/src/attribute.md

   1 # Attributes
   2
   3 An attribute is metadata applied to some module, crate or item. This metadata
   4 can be used to/for:
   5
   6 <!-- TODO: Link these to their respective examples -->
   7
   8 * [conditional compilation of code][cfg]
   9 * [set crate name, version and type (binary or library)][crate]
  10 * disable [lints][lint] (warnings)
  11 * enable compiler features (macros, glob imports, etc.)
  12 * link to a foreign library
  13 * mark functions as unit tests
  14 * mark functions that will be part of a benchmark
  15
  16 When attributes apply to a whole crate, their syntax is `#![crate_attribute]`,
  17 and when they apply to a module or item, the syntax is `#[item_attribute]`
  18 (notice the missing bang `!`).
  19
  20 Attributes can take arguments with different syntaxes:
  21
  22 * `#[attribute = "value"]`
  23 * `#[attribute(key = "value")]`
  24 * `#[attribute(value)]`
  25
  26 Attributes can have multiple values and can be separated over multiple lines, too:
  27
  28 ```rust,ignore
  29 #[attribute(value, value2)]
  30
  31
  32 #[attribute(value, value2, value3,
  33             value4, value5)]
  34 ```
  35
  36 [cfg]: attribute/cfg.md
  37 [crate]: attribute/crate.md
  38 [lint]: https://en.wikipedia.org/wiki/Lint_%28software%29