Document all attributes and macros with examples

[kud1ing]

rust.md#attributes and rust.md#macros document some attributes and macros, but give few examples. Also there are some attributes/macros missing.

Attributes:

• abi (already in rust.md; see commit 772028a)
• allow (http://static.rust-lang.org/doc/master/rust.html#lint-check-attributes)
• bench (delegated to Add doc and examples for attributes test and bench #7824)
• cfg (delegated to Document attributes cfg family #7962)
• deny (http://static.rust-lang.org/doc/master/rust.html#lint-check-attributes)
• deriving (http://static.rust-lang.org/doc/master/rust.html#deriving)
• doc (mentioned in commit 58807b0; delegated to Document attribute doc and its sub-language #7963)
• forbid (http://static.rust-lang.org/doc/master/rust.html#lint-check-attributes)
• inline: src/libsyntax/attr.rs (delegated to Document attributes inline {,always,never} #7959)
• lang (handled by document lang attribute #3342; done; see comment dbeea18 )
• license (delegated to Document no-op pass-through attributes #7961)
• link (delegated to Document attributes related to linking: link, link_args, no_link, ...?  #7960; see commit d4c40b5)
• link_args (delegated to Document attributes related to linking: link, link_args, no_link, ...?  #7960; see commit d4c40b5)
• link_name (already in rust.md; see commit 772028a)
• no_implicit_prelude, see rustc: implement a #[no_implicit_prelude] attribute. #7844
• nolink (delegated to Document attributes related to linking: link, link_args, no_link, ...?  #7960)
• no_mangle (see librustc/middle/trans/base.rs)
• no_std (see librustc/front/std_inject.rs)
• path (done; see commit d4daa78 )
• should_fail (see librustc/front/test.rs)
• start
• static_assert (see librustc/middle/trans/base.rs)
• test (delegated to Add doc and examples for attributes test and bench #7824)
• unsafe_destructor
• warn (http://static.rust-lang.org/doc/master/rust.html#lint-check-attributes)

Macros:

• asm http://static.rust-lang.org/doc/master/guide-unsafe.html#inline-assembly
• assert http://static.rust-lang.org/doc/master/std/macros/macro.assert.html
• assert_eq http://static.rust-lang.org/doc/master/std/macros/macro.assert_eq.html
• cfg http://static.rust-lang.org/doc/master/std/macros/builtin/macro.cfg.html
• cold
• concat_idents http://static.rust-lang.org/doc/master/std/macros/builtin/macro.concat_idents.html
• bytes http://static.rust-lang.org/doc/master/std/macros/builtin/macro.bytes.html
• debug (http://static.rust-lang.org/doc/master/std/logging/index.html)
• env http://static.rust-lang.org/doc/master/std/macros/builtin/macro.env.html
• error (http://static.rust-lang.org/doc/master/std/logging/index.html)
• file (http://static.rust-lang.org/doc/master/rust.html#syntax-extensions)
• format (http://static.rust-lang.org/doc/master/std/fmt/index.html)
• include (https://github.com/mozilla/rust/blob/master/doc/rust.md#syntax-extensions)
• include_bin (https://github.com/mozilla/rust/blob/master/doc/rust.md#syntax-extensions)
• include_str (https://github.com/mozilla/rust/blob/master/doc/rust.md#syntax-extensions)
• info (http://static.rust-lang.org/doc/master/std/logging/index.html)
• line http://static.rust-lang.org/doc/master/std/macros/builtin/macro.line.html
• log (http://static.rust-lang.org/doc/master/std/logging/index.html)
• log_syntax
• macro_rules
• module_path http://static.rust-lang.org/doc/master/std/macros/builtin/macro.module_path.html
• option_env http://static.rust-lang.org/doc/master/std/macros/builtin/macro.option_env.html
• proto (is gone?)
• quote_expr
• quote_item
• quote_pat
• quote_stmt
• quote_tokens
• quote_ty
• stringify (https://github.com/mozilla/rust/blob/master/doc/rust.md#syntax-extensions)
• warn (http://static.rust-lang.org/doc/master/std/logging/index.html)

[alexcrichton]

Nominating for the well-covered milestone.

[graydon]

accepted for well-covered milestone

[pnkfelix]

(the list here is too long to cope with sensibly so I am trying to make reasonably categorized sub-bugs.)

[pnkfelix]

abi has an example in rust.md; I'm going to cross it out above (with a note for why it has been struck out).

[pnkfelix]

Funny, the license attribute appears in rust.md, but not in any of our code nor is it handled in any way by the compiler. Such meta-data is propagated into the generated crate, but the current manual also says that all attribute names are effectively reserved (because only rustc interprets attributes).

Perhaps we should handle this by explicitly listing the attributes that do not and will not have a default interpretation via rustc (where license would be one of several attributes on that list)?

[pnkfelix]

Okay there are only a handful of remaining small attributes that have not been delegated to some sub-bug. They can probably be handled just by associating them with this bug directly, unless someone feels like creating a new "miscellaneous" sub-bug, or new sub-bugs for each of them.

[pnkfelix]

(and of course I haven't done anything with the list of macros yet).

[klutzy]

I've collected most attributes currently in use at wiki.

[pnkfelix]

Documentation is low-hanging fruit, but not a reason to block 1.0.

Not 1.0; P-low.

[xmo-odoo]

Is it normal that the macros doc seem to have disappeared from the official documentation?

E.g. searching for bytes! returns no match (without the bang it returns plenty of function called bytes, none of which seems to fit), and adapting the old path to http://doc.rust-lang.org/std/macros/builtin/macro.bytes.html is a 404

[huonw]

@xmo-odoo it's just a bug: #15645

[Gankra]

This is all messed up now that we have the Guide and no Tutorial.

[mdinger]

#16644 is related

[John-Nagle]

On May 12, 2013, kud1ing passed buck on "license" attribute to Bug 7961.
On Oct 24, 2013, catamorphism passed buck on Bug 7961 back to this bug.

At least two library crates won't build due to "license" attributes now being an error. (Was 3, but "stainless" was fixed. Currently broken: "http" and one other crate.)

[steveklabnik]

Checking off no_implicit_prelude, doc, no_mangle, no_std, start, static_assert, and unsafe_destructor attributes, because they have docs.

checking off license and nolink attributes because they're gone.

checking off log_syntax and macro_rules macros because they have docs

checking off proto macro because it's gone.