Merge pull request #4001 from jesse99/features/docs

Features/docs

Author: graydon

doc/README

@@ -0,0 +1,13 @@
+The markdown docs are only generated by make when node is installed (use
+`make doc`). If you don't have node installed you can generate them yourself. 
+Unfortunately there's no real standard for markdown and all the tools work 
+differently. pandoc is one that seems to work well.
+
+To generate an html version of a doc do something like:
+pandoc --from=markdown --to=html --number-sections -o build/doc/rust.html doc/rust.md && git web--browse build/doc/rust.html
+
+The syntax for pandoc flavored markdown can be found at:
+http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown
+
+A nice quick reference (for non-pandoc markdown) is at:
+http://kramdown.rubyforge.org/quickref.html

doc/rust.md

@@ -510,9 +510,8 @@ For parsing reasons, delimiters must be balanced, but they are otherwise not spe
 
 In the matcher, `$` _name_ `:` _designator_ matches the nonterminal in the
 Rust syntax named by _designator_. Valid designators are `item`, `block`,
-`stmt`, `pat`, `expr`, `ty`, `ident`, `path`, `tt`, `matchers`. The last two
-are the right-hand side and the left-hand side respectively of the `=>` in
-macro rules. In the transcriber, the designator is already known, and so only
+`stmt`, `pat`, `expr`, `ty` (type), `ident`, `path`, `matchers` (lhs of the `=>` in macro rules), 
+`tt` (rhs of the `=>` in macro rules). In the transcriber, the designator is already known, and so only
 the name of a matched nonterminal comes after the dollar sign.
 
 In both the matcher and transcriber, the Kleene star-like operator indicates repetition.
@@ -799,7 +798,7 @@ extern mod ruststd (name = "std"); // linking to 'std' under another name
 ##### Use declarations
 
 ~~~~~~~~ {.ebnf .gram}
-use_decl : "use" ident [ '=' path
+use_decl : "pub"? "use" ident [ '=' path
                           | "::" path_glob ] ;
 
 path_glob : ident [ "::" path_glob ] ?
@@ -1104,6 +1103,17 @@ Constants are declared with the `const` keyword.
 A constant item must have an expression giving its definition.
 The definition expression of a constant is limited to expression forms that can be evaluated at compile time.
 
+Constants must be explicitly typed. The type may be ```bool```, ```char```, a number, or a type derived from
+those primitive types. The derived types are borrowed pointers, static arrays, tuples, and structs.
+
+~~~~
+const bit1: uint = 1 << 0;
+const bit2: uint = 1 << 1;
+
+const bits: [uint * 2] = [bit1, bit2];
+const bits_r: &[uint] = &bits;
+~~~~
+
 ### Traits
 
 A _trait_ describes a set of method types.
@@ -1175,6 +1185,9 @@ Values with a trait type can have [methods called](#method-call-expressions) on
 for any method in the trait,
 and can be used to instantiate type parameters that are bounded by the trait.
 
+Trait methods may be static. Currently implementations of static methods behave like
+functions declared in the implentation's module.
+
 ### Implementations
 
 An _implementation_ is an item that implements a [trait](#traits) for a specific type.
@@ -1304,9 +1317,8 @@ Attributes may appear as any of
 * 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 are applied to an entity by placing them within a hash-list
-(`#[...]`) as either a prefix to the entity or as a semicolon-delimited
-declaration within the entity body.
+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.
 
 An example of attributes:
 
@@ -1326,9 +1338,9 @@ mod bar {
   ...
 }
 
-// A documentation attribute
-#[doc = "Add two numbers together."]
-fn add(x: int, y: int) { x + y }
+// A lint attribute used to suppress a warning/error
+#[allow(non_camel_case_types)]
+pub type int8_t = i8;
 ~~~~~~~~
 
 > **Note:** In future versions of Rust, user-provided extensions to the compiler will be able to interpret attributes.
@@ -1341,6 +1353,8 @@ names are effectively reserved. Some significant attributes include:
 * The `cfg` attribute, for conditional-compilation by build-configuration.
 * The `link` attribute, for describing linkage metadata for a crate.
 * The `test` attribute, for marking functions as unit tests.
+* The `allow`, `warn`, `forbid`, and `deny` attributes, for controling lint checks. Lint checks supported
+by the compiler can be found via `rustc -W help`.
 
 Other attributes may be added or removed during development of the language.
 
@@ -1546,7 +1560,9 @@ it is automatically derferenced to make the field access possible.
 ### Vector expressions
 
 ~~~~~~~~{.ebnf .gram}
-vec_expr : '[' "mut" ? [ expr [ ',' expr ] * ] ? ']'
+vec_expr : '[' "mut"? vec_elems? ']'
+
+vec_elems : [expr [',' expr]*] | [expr ',' ".." expr]
 ~~~~~~~~
 
 A [_vector_](#vector-types) _expression_ is written by enclosing zero or
@@ -1558,6 +1574,7 @@ When no mutability is specified, the vector is immutable.
 ~~~~
 [1, 2, 3, 4];
 ["a", "b", "c", "d"];
+[0, ..128];             // vector with 128 zeros
 [mut 0u8, 0u8, 0u8, 0u8];
 ~~~~
 
@@ -1889,7 +1906,7 @@ let x: int = add(1, 2);
 
 ~~~~~~~~ {.abnf .gram}
 ident_list : [ ident [ ',' ident ]* ] ? ;
-lambda_expr : '|' ident_list '| expr ;
+lambda_expr : '|' ident_list '|' expr ;
 ~~~~~~~~
 
 A _lambda expression_ (a.k.a. "anonymous function expression") defines a function and denotes it as a value,
@@ -2169,17 +2186,6 @@ Records and structures can also be pattern-matched and their fields bound to var
 When matching fields of a record,
 the fields being matched are specified first,
 then a placeholder (`_`) represents the remaining fields.
-
-A pattern that's just a variable binding,
-like `Nil` in the previous answer,
-could either refer to an enum variant that's in scope,
-or bind a new variable.
-The compiler resolves this ambiguity by forbidding variable bindings that occur in ```match``` patterns from shadowing names of variants that are in scope.
-For example, wherever ```List``` is in scope,
-a ```match``` pattern would not be able to bind ```Nil``` as a new name.
-The compiler interprets a variable pattern `x` as a binding _only_ if there is no variant named `x` in scope.
-A convention you can use to avoid conflicts is simply to name variants with upper-case letters,
-and local variables with lower-case letters.
 
 ~~~~
 # type options = {choose: bool, size: ~str};
@@ -2212,6 +2218,22 @@ fn main() {
 }
 ~~~~
 
+Patterns that bind variables default to binding to a copy of the matched value. This can be made
+explicit using the ```copy``` keyword, changed to bind to a borrowed pointer by using the ```ref```
+keyword, or to a mutable borrowed pointer using ```ref mut```, or the value can be moved into
+the new binding using ```move```.
+
+A pattern that's just an identifier,
+like `Nil` in the previous answer,
+could either refer to an enum variant that's in scope,
+or bind a new variable.
+The compiler resolves this ambiguity by forbidding variable bindings that occur in ```match``` patterns from shadowing names of variants that are in scope.
+For example, wherever ```List``` is in scope,
+a ```match``` pattern would not be able to bind ```Nil``` as a new name.
+The compiler interprets a variable pattern `x` as a binding _only_ if there is no variant named `x` in scope.
+A convention you can use to avoid conflicts is simply to name variants with upper-case letters,
+and local variables with lower-case letters.
+
 Multiple match patterns may be joined with the `|` operator.  A
 range of values may be specified with `..`. For example:
 

src/libcore/extfmt.rs

@@ -1,4 +1,46 @@
-#[doc(hidden)];
+//! Support for fmt! expressions.
+//!
+//! The syntax is close to that of Posix format strings:
+//!
+//! ~~~~~~
+//! Format := '%' Parameter? Flag* Width? Precision? Type
+//! Parameter := [0-9]+ '$'
+//! Flag := [ 0#+-]
+//! Width := Parameter | [0-9]+
+//! Precision := '.' [0-9]+
+//! Type := [bcdfiostuxX?]
+//! ~~~~~~
+//!
+//! * Parameter is the 1-based argument to apply the format to. Currently not
+//! implemented.
+//! * Flag 0 causes leading zeros to be used for padding when converting
+//! numbers.
+//! * Flag # causes the conversion to be done in an *alternative* manner.
+//! Currently not implemented.
+//! * Flag + causes signed numbers to always be prepended with a sign
+//! character.
+//! * Flag - left justifies the result
+//! * Width specifies the minimum field width of the result. By default
+//! leading spaces are added.
+//! * Precision specifies the minimum number of digits for integral types
+//! and the minimum number
+//! of decimal places for float.
+//!
+//! The types currently supported are:
+//!
+//! * b - bool
+//! * c - char
+//! * d - int
+//! * f - float
+//! * i - int (same as d)
+//! * o - uint as octal
+//! * t - uint as binary
+//! * u - uint
+//! * x - uint as lower-case hexadecimal
+//! * X - uint as upper-case hexadecimal
+//! * s - str (any flavor)
+//! * ? - arbitrary type (does not use the to_str trait)
+
 // NB: transitionary, de-mode-ing.
 #[forbid(deprecated_mode)];
 #[forbid(deprecated_pattern)];
@@ -44,6 +86,7 @@ use option::{Some, None};
  */
 
 // Functions used by the fmt extension at compile time
+#[doc(hidden)]
 pub mod ct {
     pub enum Signedness { Signed, Unsigned, }
     pub enum Caseness { CaseUpper, CaseLower, }
@@ -277,6 +320,7 @@ pub mod ct {
 // decisions made a runtime. If it proves worthwhile then some of these
 // conditions can be evaluated at compile-time. For now though it's cleaner to
 // implement it 0this way, I think.
+#[doc(hidden)]
 pub mod rt {
     pub const flag_none : u32 = 0u32;
     pub const flag_left_justify   : u32 = 0b00000000000001u32;
@@ -483,6 +527,7 @@ pub mod rt {
     }
 }
 
+// Bulk of the tests are in src/test/run-pass/syntax-extension-fmt.rs
 #[cfg(test)]
 mod test {
     #[test]