Attribute cleanup

[ehuss]

I would like to regroup and update the attributes page, and I would like some feedback on how to best improve it. Some of my goals are:

• Every attribute should have a dedicated section somewhere in the reference, making it easy to link to them.
• Every attribute should explain the format of its syntax for its meta input (this is finished in my local branch).
• Every attribute should be documented well enough to understand what it does and how it works.
• Remove the "Crate-only" and "Misc" sections (or at least shrink "misc").
• Ensure all the "Attributes on" sections exist and are complete (Add "Attributes on X" for various places attributes are allowed #355).
• Maybe avoid using attributes.md as a dumping ground for random attributes?

I think the last point may be the most debatable. Right now, to me, it appears as just a giant page that is difficult to navigate. I think it would be good to move the details off to separate pages, and just have an index in attributes.md that links to where to find each one. This is already done for about half the attributes. Unfortunately it's not really clear where some of the other attributes should live.

Here is a preliminary outline of how I think such an index would look, and where the attributes link to.

• Conditional Compilation
  • cfg (conditional-compilation.md)
  • cfg_attr (conditional-compilation.md)
• Testing
  • test
  • ignore
  • should_panic
• Derive
  • derive
  • automatically_derived (currently undocumented)
• Macro-related
  • macro_use (FUTURE macros-by-example.md)
  • macro_export (FUTURE macros-by-example.md)
  • proc_macro (procedural-macros.md)
  • proc_macro_derive (procedural-macros.md)
  • proc_macro_attribute (procedural-macros.md)
• Lint Check
  • allow
  • deny
  • forbid
  • warn
  • must_use
  • Tool lints
• Linking, Symbols, and FFI
  • link (external-blocks.md)
  • link_name (external-blocks.md???)
  • no_link (MAYBE extern-crates.md?)
  • repr (type-layout.md)
  • crate_type (linkage.md)
  • no_main
  • no_start
  • export_name (abi.md)
  • link_section (abi.md)
  • no_mangle (abi.md)
  • used (abi.md)
  • crate_name
  • windows_subsystem
• Code Generation
  • inline
  • cold
  • no_builtins
  • target_feature (undocumented)
• Compiler Settings
  • feature (undocumented)
  • recursion_limit
  • type_length_limit (undocumented)
• Documentation
  • doc (rustdoc book)
• Preludes
  • no_std (crates-and-source-files.md)
  • no_implicit_prelude (modules.md)
• Deprecation
  • deprecated (maybe move this to lints or documentation?)
• path (modules.md)
• Runtime
  • panic_handler (runtime.md)
  • global_allocator (??? is this runtime?)
• Tool

I'm thinking maybe just moving some of these to dedicated pages (testing, lints, code generation, etc.)

Any thoughts? Ideas on how to better organize? Does this sound terrible?

[Centril]

Maybe avoid using attributes.md as a dumping ground for random attributes?

I think the attributes.md page should serve as a specification of grammar. I think:

• https://github.com/rust-lang-nursery/reference/blob/master/src/attributes.md#attributes
• https://github.com/rust-lang-nursery/reference/blob/master/src/attributes.md#meta-item-attribute-syntax
• https://github.com/rust-lang-nursery/reference/blob/master/src/attributes.md#active-and-inert-attributes

are relevant to keep. In particular, meta-item-attribute-syntax is good. The rest can be slimmed down so that they link to the relevant elaborations of specific attributes. attributes.md may serve as a "start here" page.

Macro-related

Consider moving proc macro related stuff into a subsection below this one.

• Derive

Be sure to link to the proc macro page for proc_macro_derive and vice versa.

Lint Check

I think there's a distinction here to be made between generic "lint control" mechanisms (allow, warn, ...) and specific "lint triggering" (must_use, deprecated, tool lints, and other similar attributes in the future).

Code Generation

I think a fruitful distinction may be hints and non-hints since hints are not a matter of correctness.
I.e. hints like #[inline] take no part in the formal semantics.

• global_allocator (??? is this runtime?)

Absolutely it is!

Does this sound terrible?

The basic idea sounds great and most of the categorization makes sense; let's iterate with what you suggested and possibly with my notes above.

[Havvy]

Does this sound terrible?
No! Quite the opposite! This is a great writeup!

What I wanted to do before losing all motivation was to change the Table of Contents to make Attributes its own main chapter separate from Items, and then move the listing of attributes into a subchapter. You want multiple subchapters in this proposal and I'm neutral on which is better. I can't remember what exactly was blocking me on that; only that I wanted some other PRs to be merged first to avoid merge conflicts.

Ensure all the "Attributes on" sections exist and are complete (#355).

I should get this done.