manual: many fixes

Mostly around attributes and language items.

Author: emberian

src/doc/rust.md

@@ -611,7 +611,7 @@ Attributes on the anonymous crate module define important metadata that influenc
 the behavior of the compiler.
 
 ~~~~
-// Package ID
+// Crate ID
 #[ crate_id = "projx#2.5" ];
 
 // Additional metadata attributes
@@ -792,7 +792,7 @@ extern crate std; // equivalent to: extern crate std = "std";
 
 extern crate ruststd = "std"; // linking to 'std' under another name
 
-extern crate foo = "some/where/rust-foo#foo:1.0"; // a full package ID for external tools
+extern crate foo = "some/where/rust-foo#foo:1.0"; // a full crate ID for external tools
 ~~~~
 
 ##### Use declarations
@@ -1505,11 +1505,9 @@ specified name.
 extern { }
 ~~~~
 
-The type of a function
-declared in an extern block
-is `extern "abi" fn(A1, ..., An) -> R`,
-where `A1...An` are the declared types of its arguments
-and `R` is the decalred return type.
+The type of a function declared in an extern block is `extern "abi" fn(A1,
+..., An) -> R`, where `A1...An` are the declared types of its arguments and
+`R` is the declared return type.
 
 ## Visibility and Privacy
 
@@ -1680,41 +1678,43 @@ import public items from their destination, not private items.
 ## Attributes
 
 ~~~~ {.notrust .ebnf .gram}
-attribute : '#' '[' attr_list ']' ;
-attr_list : attr [ ',' attr_list ]* ;
+attribute : '#' '!' ? '[' attr_list ']'
+attr_list : attr [ ',' attr_list ]*
 attr : ident [ '=' literal
-             | '(' attr_list ')' ] ? ;
+             | '(' attr_list ')' ] ?
 ~~~~
 
 Static entities in Rust -- crates, modules and items -- may have _attributes_
-applied to them. ^[Attributes in Rust are modeled on Attributes in ECMA-335,
-C#]
-An attribute is a general, free-form metadatum that is interpreted according to name, convention, and language and compiler version.
-Attributes may appear as any of
+applied to them. Attributes in Rust are modeled on Attributes in ECMA-335, C#.
+An attribute is a general, free-form metadatum that is interpreted according
+to name, convention, and language and compiler version.  Attributes may appear
+as any of:
 
 * A single identifier, the attribute name
-* An identifier followed by the equals sign '=' and a literal, providing a key/value pair
+* An identifier followed by the equals sign '=' and a literal, providing a
+  key/value pair
 * An identifier followed by a parenthesized list of sub-attribute arguments
 
-Attributes terminated by a semi-colon apply to the entity that the attribute is declared
-within. Attributes that are not terminated by a semi-colon apply to the next entity.
+Attributes with a bang ("!") after the hash ("#") apply to the item that the
+attribute is declared within. Attributes that do not have a bang after the
+hash by a semi-colon apply to the next item.
 
 An example of attributes:
 
-~~~~ {.ignore}
+~~~~
 // General metadata applied to the enclosing module or crate.
-#[license = "BSD"];
+#![license = "BSD"]
 
 // A function marked as a unit test
 #[test]
 fn test_foo() {
-  ...
+  /* ... */
 }
 
 // A conditionally-compiled module
 #[cfg(target_os="linux")]
 mod bar {
-  ...
+  /* ... */
 }
 
 // A lint attribute used to suppress a warning/error
@@ -1727,29 +1727,85 @@ pub type int8_t = i8;
 > effectively no difference between an attribute handled by a loadable syntax
 > extension and the compiler.
 
-Some significant attributes include:
-
-* The `doc` attribute, for documenting code in-place.
-* The `cfg` attribute, for conditional-compilation by build-configuration (see
-  [Conditional compilation](#conditional-compilation)).
-* The `crate_id` attribute, for describing the package ID of a crate.
-* The `lang` attribute, for custom definitions of traits and functions that are
-  known to the Rust compiler (see [Language items](#language-items)).
-* The `link` attribute, for describing linkage metadata for a extern blocks.
-* The `test` attribute, for marking functions as unit tests.
-* The `allow`, `warn`, `forbid`, and `deny` attributes, for
-  controlling lint checks (see [Lint check attributes](#lint-check-attributes)).
-* The `deriving` attribute, for automatically generating implementations of
-  certain traits.
-* The `inline` attribute, for expanding functions at caller location (see
-  [Inline attributes](#inline-attributes)).
-* The `static_assert` attribute, for asserting that a static bool is true at
-  compiletime.
-* The `thread_local` attribute, for defining a `static mut` as a thread-local.
-  Note that this is only a low-level building block, and is not local to a
-  *task*, nor does it provide safety.
-
-Other attributes may be added or removed during development of the language.
+### Crate-only attributes
+
+- `crate_type` - see [linkage](#linkage).
+- `feature` - see [compiler features](#compiler-features).
+- `no_start` - disable linking to the `native` crate, which specifies the
+  "start" language item.
+- `no_main` - disable emitting the `main` symbol. Useful when some
+  other object being linked to defines `main`.
+- `no_std` - disable linking to the `std` crate.
+- `crate_id` - specify the this crate's crate ID.
+
+### Module-only attributes
+
+- `path` - specifies the file to load the module from. `#[path="foo.rs"] mod
+  bar;` is equivalent to `mod bar { /* contents of foo.rs */ }`
+- `macro_escape` - macros defined in this module will be visible in the
+  module's parent, after this module has been included.
+- `no_implicit_prelude` - disable injecting `use std::prelude::*` in this
+  module.
+
+### Function-only attributes
+
+- `start` - indicates that this function should be used as the entry point,
+  overriding the "start" language item.  See the "start" [language
+  item](#language-items) for more details.
+- `main` - indicates that this function should be passed to the entry point,
+  rather than the function in the crate root named `main`.
+- `macro_registrar` - when using loadable syntax extensions, mark this
+  function as the registration point for the current crate's syntax
+  extensions.
+
+### Static-only attributes
+
+- `thread_local` - on a `static mut`, this signals that the value of this
+  static may change depending on the current thread. The exact consequences of
+  this are implementation-defined.
+- `address_insignificant` - references to this static may alias with
+  references to other statics, potentially of unrelated type.
+
+### FFI attributes
+
+On an `extern` block, the following attributes are interpreted:
+
+- `link` - indicate that a native library should be linked to for the
+  declarations in this block to be linked correctly. See [external
+  blocks](#external-blocks)
+- `link_args` - specify arguments to the linker, rather than just the library
+  name and type. This is feature gated and the exact behavior is
+  implementation-defined (due to variety of linker invocation syntax).
+
+On declarations inside an `extern` block, the following attributes are
+interpreted:
+
+- `link_name` - the name of the symbol that this function or static should be
+  imported as.
+- `linkage` - on a static, this specifies the [linkage
+  type](http://llvm.org/docs/LangRef.html#linkage-types).
+
+### Miscellaneous attributes
+
+- `simd` - on certain tuple structs, derive the arithmetic operators, which
+  lower to the target's SIMD instructions, if any.
+- `link_section` - on statics and functions, this specifies the section of the
+  object file that this item's contents will be placed into.
+- `static_assert` - on statics whose type is `bool`, terminates compilation
+  with an error if it is not initialized to `true`.
+- `repr` - on C-like enums, this sets the underlying type used for
+  representation. Useful for FFI.
+- `no_mangle` - on any item, do not apply the standard name mangling. Set the
+  symbol for this item to its identifier.
+- `packed` - on structs or enums, eliminate any padding that would be used to
+  align fields.
+- `unsafe_destructor` - allow implementations of the "drop" language item
+  where the type it is implemented for does not implement the "send" language
+  item.
+- `unsafe_no_drop_flag` - on structs, remove the flag that prevents
+  destructors from being run twice. Destructors might be run multiple times on
+  the same object with this attribute.
+- `macro_export` - export a macro for cross-crate usage.
 
 ### Conditional compilation
 
@@ -1791,9 +1847,7 @@ one of `foo` and `bar` to be defined (this resembles in the disjunctive normal
 form). Additionally, one can reverse a condition by enclosing it in a
 `not(...)`, like e. g. `#[cfg(not(target_os = "win32"))]`.
 
-To pass a configuration option which triggers a `#[cfg(identifier)]` one can use
-`rustc --cfg identifier`. In addition to that, the following configurations are
-pre-defined by the compiler:
+The following configurations must be defined by the implementation:
 
  * `target_arch = "..."`. Target CPU architecture, such as `"x86"`, `"x86_64"`
    `"mips"`, or `"arm"`.
@@ -1805,8 +1859,8 @@ pre-defined by the compiler:
  * `target_os = "..."`. Operating system of the target, examples include
    `"win32"`, `"macos"`, `"linux"`, `"android"` or `"freebsd"`.
  * `target_word_size = "..."`. Target word size in bits. This is set to `"32"`
-   for 32-bit CPU targets, and likewise set to `"64"` for 64-bit CPU targets.
- * `test`. Only set in test builds (`rustc --test`).
+   for targets with 32-bit pointers, and likewise set to `"64"` for 64-bit
+   pointers.
  * `unix`. See `target_family`.
  * `windows`. See `target_family`.
 
@@ -1823,7 +1877,7 @@ For any lint check `C`:
  * `allow(C)` overrides the check for `C` so that violations will go
     unreported,
  * `forbid(C)` is the same as `deny(C)`, but also forbids uses of
-   `allow(C)` within the entity.
+   `allow(C)` within the attribute.
 
 The lint checks supported by the compiler can be found via `rustc -W help`,
 along with their default settings.
@@ -1881,11 +1935,11 @@ mod m3 {
 
 ### Language items
 
-Some primitive Rust operations are defined in Rust code,
-rather than being implemented directly in C or assembly language.
-The definitions of these operations have to be easy for the compiler to find.
-The `lang` attribute makes it possible to declare these operations.
-For example, the `str` module in the Rust standard library defines the string equality function:
+Some primitive Rust operations are defined in Rust code, rather than being
+implemented directly in C or assembly language.  The definitions of these
+operations have to be easy for the compiler to find.  The `lang` attribute
+makes it possible to declare these operations.  For example, the `str` module
+in the Rust standard library defines the string equality function:
 
 ~~~~ {.ignore}
 #[lang="str_eq"]
@@ -1900,16 +1954,23 @@ when generating calls to the string equality function.
 
 A complete list of the built-in language items follows:
 
-#### Traits
+#### Built-in Traits
 
-`const`
-  : Cannot be mutated.
-`owned`
-  : Are uniquely owned.
-`durable`
-  : Contain references.
+`send`
+  : Able to be sent across task boundaries.
+`sized`
+  : Has a size known at compile time.
+`copy`
+  : Types that do not move ownership when used by-value.
+`share`
+  : Able to be safely shared between tasks when aliased.
 `drop`
-  : Have finalizers.
+  : Have destructors.
+
+#### Operators
+
+These language items are traits:
+
 `add`
   : Elements can be added (for example, integers and floats).
 `sub`
@@ -1940,17 +2001,54 @@ A complete list of the built-in language items follows:
   : Elements can be compared for equality.
 `ord`
   : Elements have a partial ordering.
+`deref`
+  : `*` can be applied, yielding a reference to another type
+`deref_mut`
+  : `*` can be applied, yielding a mutable reference to another type
 
-#### Operations
+
+These are functions:
 
 `str_eq`
-  : Compare two strings for equality.
+  : Compare two strings (`&str`) for equality.
 `uniq_str_eq`
-  : Compare two owned strings for equality.
-`annihilate`
-  : Destroy a box before freeing it.
-`log_type`
-  : Generically print a string representation of any type.
+  : Compare two owned strings (`~str`) for equality.
+`strdup_uniq`
+  : Return a new unique string
+    containing a copy of the contents of a unique string.
+
+#### Types
+
+`unsafe`
+  : A type whose contents can be mutated through an immutable reference
+`type_id`
+  : The type returned by the `type_id` intrinsic.
+
+#### Marker types
+
+These types help drive the compiler's analysis
+
+`covariant_type`
+  : The type parameter should be considered covariant
+`contravariant_type`
+  : The type parameter should be considered contravariant
+`invariant_type`
+  : The type parameter should be considered invariant
+`covariant_lifetime`
+  : The lifetime parameter should be considered covariant
+`contravariant_lifetime`
+  : The lifetime parameter should be considered contravariant
+`invariant_lifetime`
+  : The lifetime parameter should be considered invariant
+`no_send_bound`
+  : This type does not implement "send", even if eligible
+`no_copy_bound`
+  : This type does not implement "copy", even if eligible
+`no_share_bound`
+  : This type does not implement "share", even if eligible
+`managed_bound`
+  : This type implements "managed"
+
 `fail_`
   : Abort the program with an error.
 `fail_bounds_check`
@@ -1963,15 +2061,6 @@ A complete list of the built-in language items follows:
   : Allocate memory on the managed heap.
 `free`
   : Free memory that was allocated on the managed heap.
-`borrow_as_imm`
-  : Create an immutable reference to a mutable value.
-`return_to_mut`
-  : Release a reference created with `return_to_mut`
-`check_not_borrowed`
-  : Fail if a value has existing references to it.
-`strdup_uniq`
-  : Return a new unique string
-    containing a copy of the contents of a unique string.
 
 > **Note:** This list is likely to become out of date. We should auto-generate it
 > from `librustc/middle/lang_items.rs`.
@@ -2039,6 +2128,7 @@ Supported traits for `deriving` are:
 * `Show`, to format a value using the `{}` formatter.
 
 ### Stability
+
 One can indicate the stability of an API using the following attributes:
 
 * `deprecated`: This item should no longer be used, e.g. it has been
@@ -2101,18 +2191,18 @@ necessarily ready for every-day use. These features are often of "prototype
 quality" or "almost production ready", but may not be stable enough to be
 considered a full-fleged language feature.
 
-For this reason, rust recognizes a special crate-level attribute of the form:
+For this reason, Rust recognizes a special crate-level attribute of the form:
 
 ~~~~ {.ignore}
-#[feature(feature1, feature2, feature3)]
+#![feature(feature1, feature2, feature3)]
 ~~~~
 
 This directive informs the compiler that the feature list: `feature1`,
 `feature2`, and `feature3` should all be enabled. This is only recognized at a
 crate-level, not at a module-level. Without this directive, all features are
 considered off, and using the features will result in a compiler error.
 
-The currently implemented features of the compiler are:
+The currently implemented features of the reference compiler are:
 
 * `macro_rules` - The definition of new macros. This does not encompass
                   macro-invocation, that is always enabled by default, this only