---

yaml
---
r: 144311
b: refs/heads/try2
c: 5e5e2c7
h: refs/heads/master
i:
  144309: 3a32d84
  144307: 6b64e7a
  144303: 48df8ab
v: v3

Author: bors

[refs]

@@ -5,7 +5,7 @@ refs/heads/snap-stage3: 78a7676898d9f80ab540c6df5d4c9ce35bb50463
 refs/heads/try: 519addf6277dbafccbb4159db4b710c37eaa2ec5
 refs/tags/release-0.1: 1f5c5126e96c79d22cb7862f75304136e204f105
 refs/heads/ndm: f3868061cd7988080c30d6d5bf352a5a5fe2460b
-refs/heads/try2: 0081961c57494162d9f2d19265175af95fbdd8d7
+refs/heads/try2: 5e5e2c71e403371ff8a5d5430e7696654214a438
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/configure

@@ -739,7 +739,9 @@ do
     make_dir $h/test/doc-tutorial-ffi
     make_dir $h/test/doc-tutorial-macros
     make_dir $h/test/doc-tutorial-borrowed-ptr
+    make_dir $h/test/doc-tutorial-container
     make_dir $h/test/doc-tutorial-tasks
+    make_dir $h/test/doc-tutorial-conditions
     make_dir $h/test/doc-rust
 done
 

branches/try2/doc/rust.md

@@ -788,7 +788,7 @@ extern mod complicated_mod = "some-file/in/the-rust/path";
 ##### Use declarations
 
 ~~~~~~~~ {.ebnf .gram}
-use_decl : "pub"? "use" ident [ '=' path
+use_decl : "pub" ? "use" ident [ '=' path
                           | "::" path_glob ] ;
 
 path_glob : ident [ "::" path_glob ] ?
@@ -851,6 +851,38 @@ In this example, the module `quux` re-exports all of the public names defined in
 
 Also note that the paths contained in `use` items are relative to the crate root.
 So, in the previous example, the `use` refers to `quux::foo::*`, and not simply to `foo::*`.
+This also means that top-level module declarations should be at the crate root if direct usage
+of the declared modules within `use` items is desired.  It is also possible to use `self` and `super`
+at the beginning of a `use` item to refer to the current and direct parent modules respectively.
+All rules regarding accessing declared modules in `use` declarations applies to both module declarations
+and `extern mod` declarations.
+
+An example of what will and will not work for `use` items:
+~~~~
+# #[allow(unused_imports)];
+use foo::extra;          // good: foo is at the root of the crate
+use foo::baz::foobaz;    // good: foo is at the root of the crate
+
+mod foo {
+    extern mod extra;
+
+    use foo::extra::list;  // good: foo is at crate root
+//  use extra::*;          // bad:  extra is not at the crate root
+    use self::baz::foobaz; // good: self refers to module 'foo'
+    use foo::bar::foobar;  // good: foo is at crate root
+
+    pub mod bar {
+        pub fn foobar() { }
+    }
+
+    pub mod baz {
+        use super::bar::foobar; // good: super refers to module 'foo'
+        pub fn foobaz() { }
+    }
+}
+
+fn main() {}
+~~~~
 
 ### Functions
 
@@ -1006,20 +1038,25 @@ code_. They are defined in the same way as any other Rust function,
 except that they have the `extern` modifier.
 
 ~~~
+// Declares an extern fn, the ABI defaults to "C" 
 extern fn new_vec() -> ~[int] { ~[] }
+
+// Declares an extern fn with "stdcall" ABI
+extern "stdcall" fn new_vec_stdcall() -> ~[int] { ~[] }
 ~~~
 
-Extern functions may not be called from Rust code,
-but Rust code may take their value as a raw `u8` pointer.
+Unlike normal functions, extern fns have an `extern "ABI" fn()`.
+This is the same type as the functions declared in an extern
+block.
 
 ~~~
 # extern fn new_vec() -> ~[int] { ~[] }
-let fptr: *u8 = new_vec;
+let fptr: extern "C" fn() -> ~[int] = new_vec;
 ~~~
 
-The primary motivation for extern functions is
-to create callbacks for foreign functions that expect to receive function
-pointers.
+Extern functions may be called from Rust code, but
+caution must be taken with respect to the size of the stack
+segment, just as when calling an extern function normally.
 
 ### Type definitions
 
@@ -1384,14 +1421,13 @@ between the Rust ABI and the foreign ABI.
 A number of [attributes](#attributes) control the behavior of external
 blocks.
 
-By default external blocks assume
-that the library they are calling uses the standard C "cdecl" ABI.
-Other ABIs may be specified using the `abi` attribute as in
+By default external blocks assume that the library they are calling
+uses the standard C "cdecl" ABI.  Other ABIs may be specified using
+an `abi` string, as shown here:
 
 ~~~{.xfail-test}
 // Interface to the Windows API
-#[abi = "stdcall"]
-extern { }
+extern "stdcall" { }
 ~~~
 
 The `link_name` attribute allows the name of the library to be specified.
@@ -1407,6 +1443,12 @@ This is particularly useful for creating external blocks for libc,
 which tends to not follow standard library naming conventions
 and is linked to all Rust programs anyway.
 
+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.
+
 ## Attributes
 
 ~~~~~~~~{.ebnf .gram}
@@ -1920,7 +1962,7 @@ it is automatically dereferenced to make the field access possible.
 ### Vector expressions
 
 ~~~~~~~~{.ebnf .gram}
-vec_expr : '[' "mut"? vec_elems? ']'
+vec_expr : '[' "mut" ? vec_elems? ']'
 
 vec_elems : [expr [',' expr]*] | [expr ',' ".." expr]
 ~~~~~~~~
@@ -2864,17 +2906,16 @@ the vtable pointer for the `T` implementation of `R`, and the pointer value of `
 An example of an object type:
 
 ~~~~~~~~
-# use std::int;
 trait Printable {
-  fn to_str(&self) -> ~str;
+  fn to_string(&self) -> ~str;
 }
 
 impl Printable for int {
-  fn to_str(&self) -> ~str { int::to_str(*self) }
+  fn to_string(&self) -> ~str { self.to_str() }
 }
 
 fn print(a: @Printable) {
-   println(a.to_str());
+   println(a.to_string());
 }
 
 fn main() {