---

yaml
---
r: 152699
b: refs/heads/try2
c: b09985e
h: refs/heads/master
i:
  152697: afbe1cf
  152695: 3aacec5
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: cb89880e6dc3311421ead1e656361ccf4c8e6e29
+refs/heads/try2: b09985e702cd849f0e352d2a80be601296138d45
 refs/heads/dist-snap: ba4081a5a8573875fed17545846f6f6902c8ba8d
 refs/tags/release-0.2: c870d2dffb391e14efb05aa27898f1f6333a9596
 refs/tags/release-0.3: b5f0d0f648d9a6153664837026ba1be43d3e2503

branches/try2/src/doc/guide-testing.md

@@ -4,7 +4,7 @@
 
 To create test functions, add a `#[test]` attribute like this:
 
-~~~
+~~~test_harness
 fn return_two() -> int {
     2
 }
@@ -37,7 +37,7 @@ test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured
 Rust has built in support for simple unit testing. Functions can be
 marked as unit tests using the `test` attribute.
 
-~~~
+~~~test_harness
 #[test]
 fn return_none_if_empty() {
     // ... test code ...
@@ -55,7 +55,7 @@ other (`assert_eq`, ...) means, then the test fails.
 When compiling a crate with the `--test` flag `--cfg test` is also
 implied, so that tests can be conditionally compiled.
 
-~~~
+~~~test_harness
 #[cfg(test)]
 mod tests {
     #[test]
@@ -80,11 +80,11 @@ Tests that are intended to fail can be annotated with the
 task to fail then the test will be counted as successful; otherwise it
 will be counted as a failure. For example:
 
-~~~
+~~~test_harness
 #[test]
 #[should_fail]
 fn test_out_of_bounds_failure() {
-    let v: [int] = [];
+    let v: &[int] = [];
     v[0];
 }
 ~~~
@@ -204,26 +204,22 @@ amount.
 
 For example:
 
-~~~
-# #![allow(unused_imports)]
+~~~test_harness
 extern crate test;
 
-use std::slice;
 use test::Bencher;
 
 #[bench]
 fn bench_sum_1024_ints(b: &mut Bencher) {
-    let v = slice::from_fn(1024, |n| n);
-    b.iter(|| {v.iter().fold(0, |old, new| old + *new);} );
+    let v = Vec::from_fn(1024, |n| n);
+    b.iter(|| v.iter().fold(0, |old, new| old + *new));
 }
 
 #[bench]
 fn initialise_a_vector(b: &mut Bencher) {
-    b.iter(|| {slice::from_elem(1024, 0u64);} );
+    b.iter(|| Vec::from_elem(1024, 0u64));
     b.bytes = 1024 * 8;
 }
-
-# fn main() {}
 ~~~
 
 The benchmark runner will calibrate measurement of the benchmark
@@ -266,19 +262,16 @@ benchmarking what one expects. For example, the compiler might
 recognize that some calculation has no external effects and remove
 it entirely.
 
-~~~
-# #![allow(unused_imports)]
+~~~test_harness
 extern crate test;
 use test::Bencher;
 
 #[bench]
 fn bench_xor_1000_ints(b: &mut Bencher) {
     b.iter(|| {
-            range(0, 1000).fold(0, |old, new| old ^ new);
-        });
+        range(0, 1000).fold(0, |old, new| old ^ new);
+    });
 }
-
-# fn main() {}
 ~~~
 
 gives the following results
@@ -297,8 +290,11 @@ cannot remove the computation entirely. This could be done for the
 example above by adjusting the `bh.iter` call to
 
 ~~~
-# struct X; impl X { fn iter<T>(&self, _: || -> T) {} } let bh = X;
-bh.iter(|| range(0, 1000).fold(0, |old, new| old ^ new))
+# struct X; impl X { fn iter<T>(&self, _: || -> T) {} } let b = X;
+b.iter(|| {
+    // note lack of `;` (could also use an explicit `return`).
+    range(0, 1000).fold(0, |old, new| old ^ new)
+});
 ~~~
 
 Or, the other option is to call the generic `test::black_box`
@@ -309,10 +305,10 @@ forces it to consider any argument as used.
 extern crate test;
 
 # fn main() {
-# struct X; impl X { fn iter<T>(&self, _: || -> T) {} } let bh = X;
-bh.iter(|| {
-        test::black_box(range(0, 1000).fold(0, |old, new| old ^ new));
-    });
+# struct X; impl X { fn iter<T>(&self, _: || -> T) {} } let b = X;
+b.iter(|| {
+    test::black_box(range(0, 1000).fold(0, |old, new| old ^ new));
+});
 # }
 ~~~
 

branches/try2/src/doc/index.md

@@ -67,12 +67,26 @@ li {list-style-type: none; }
 
 * [The `rustdoc` manual](rustdoc.html)
 
-# External resources
+# External documentation
 
-* The Rust IRC channels on [irc.mozilla.org](http://irc.mozilla.org/)
+*Note: While these are great resources for learning Rust, they may
+track a particular version of Rust that is likely not exactly the same
+as that for which this documentation was generated.*
+
+* [Rust for Rubyists] - An excellent introduction for Rust; not just for Rubyists (tracks the most recent release).
+* [Rust by Example] - Short examples of common tasks in Rust (tracks the master branch).
+* [The Rust wiki](http://github.com/rust-lang/rust/wiki)
+
+[Rust for Rubyists]: http://www.rustforrubyists.com/
+[Rust by Example]: http://rustbyexample.com/
+
+# Community
+
+* [Reddit](http://reddit.com/r/rust)
+* [Stack Overflow](http://stackoverflow.com/questions/tagged/rust)
+* The Rust IRC channels on [irc.mozilla.org](http://irc.mozilla.org/):
     * [`#rust`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust) - general discussion
     * [`#rust-gamedev`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-gamedev) - game development
     * [`#rust-internals`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals) - compiler and libraries
     * [`#rust-osdev`](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-osdev) - operating system development
-* The Rust community on [Reddit](http://reddit.com/r/rust)
-* The Rust [wiki](http://github.com/rust-lang/rust/wiki)
+

branches/try2/src/doc/rustdoc.md

@@ -171,6 +171,18 @@ You can specify that the code block should be compiled but not run with the
 ```
 ~~~
 
+Lastly, you can specify that a code block be compiled as if `--test`
+were passed to the compiler using the `test_harness` directive.
+
+~~~md
+```test_harness
+#[test]
+fn foo() {
+    fail!("oops! (will run & register as failure)")
+}
+```
+~~~
+
 Rustdoc also supplies some extra sugar for helping with some tedious
 documentation examples. If a line is prefixed with `# `, then the line
 will not show up in the HTML documentation, but it will be used when

branches/try2/src/librustdoc/html/layout.rs

@@ -63,7 +63,7 @@ r##"<!DOCTYPE html>
             <div class="search-container">
                 <input class="search-input" name="search"
                        autocomplete="off"
-                       placeholder="Click or press 's' to search, '?' for more options..."
+                       placeholder="Click or press 'S' to search, '?' for more options..."
                        type="search">
             </div>
         </form>
@@ -82,9 +82,9 @@ r##"<!DOCTYPE html>
                 <dd>Show this help dialog</dd>
                 <dt>S</dt>
                 <dd>Focus the search field</dd>
-                <dt>&uarr;</dt>
+                <dt>&larrb;</dt>
                 <dd>Move up in search results</dd>
-                <dt>&darr;</dt>
+                <dt>&rarrb;</dt>
                 <dd>Move down in search results</dd>
                 <dt>&#9166;</dt>
                 <dd>Go to active search result</dd>

branches/try2/src/librustdoc/html/markdown.rs

@@ -174,8 +174,7 @@ pub fn render(w: &mut fmt::Formatter, s: &str, print_toc: bool) -> fmt::Result {
                     slice::raw::buf_as_slice((*lang).data,
                                            (*lang).size as uint, |rlang| {
                         let rlang = str::from_utf8(rlang).unwrap();
-                        let (_,_,_,notrust) = parse_lang_string(rlang);
-                        if notrust {
+                        if LangString::parse(rlang).notrust {
                             (my_opaque.dfltblk)(ob, &buf, lang,
                                                 opaque as *mut libc::c_void);
                             true
@@ -196,7 +195,7 @@ pub fn render(w: &mut fmt::Formatter, s: &str, print_toc: bool) -> fmt::Result {
                             stripped_filtered_line(l).unwrap_or(l)
                         }).collect::<Vec<&str>>().connect("\n");
                         let krate = krate.as_ref().map(|s| s.as_slice());
-                        let test = test::maketest(test.as_slice(), krate, false);
+                        let test = test::maketest(test.as_slice(), krate, false, false);
                         s.push_str(format!("<span id='rust-example-raw-{}' \
                                              class='rusttest'>{}</span>",
                                            i, Escape(test.as_slice())).as_slice());
@@ -309,16 +308,16 @@ pub fn find_testable_code(doc: &str, tests: &mut ::test::Collector) {
                     lang: *hoedown_buffer, opaque: *mut libc::c_void) {
         unsafe {
             if text.is_null() { return }
-            let (should_fail, no_run, ignore, notrust) = if lang.is_null() {
-                (false, false, false, false)
+            let block_info = if lang.is_null() {
+                LangString::all_false()
             } else {
                 slice::raw::buf_as_slice((*lang).data,
                                        (*lang).size as uint, |lang| {
                     let s = str::from_utf8(lang).unwrap();
-                    parse_lang_string(s)
+                    LangString::parse(s)
                 })
             };
-            if notrust { return }
+            if block_info.notrust { return }
             slice::raw::buf_as_slice((*text).data, (*text).size as uint, |text| {
                 let opaque = opaque as *mut hoedown_html_renderer_state;
                 let tests = &mut *((*opaque).opaque as *mut ::test::Collector);
@@ -327,7 +326,9 @@ pub fn find_testable_code(doc: &str, tests: &mut ::test::Collector) {
                     stripped_filtered_line(l).unwrap_or(l)
                 });
                 let text = lines.collect::<Vec<&str>>().connect("\n");
-                tests.add_test(text.to_string(), should_fail, no_run, ignore);
+                tests.add_test(text.to_string(),
+                               block_info.should_fail, block_info.no_run,
+                               block_info.ignore, block_info.test_harness);
             })
         }
     }
@@ -365,33 +366,52 @@ pub fn find_testable_code(doc: &str, tests: &mut ::test::Collector) {
     }
 }
 
-fn parse_lang_string(string: &str) -> (bool,bool,bool,bool) {
-    let mut seen_rust_tags = false;
-    let mut seen_other_tags = false;
-    let mut should_fail = false;
-    let mut no_run = false;
-    let mut ignore = false;
-    let mut notrust = false;
-
-    let mut tokens = string.as_slice().split(|c: char|
-      !(c == '_' || c == '-' || c.is_alphanumeric())
-    );
-
-    for token in tokens {
-        match token {
-            "" => {},
-            "should_fail" => { should_fail = true; seen_rust_tags = true; },
-            "no_run" => { no_run = true; seen_rust_tags = true; },
-            "ignore" => { ignore = true; seen_rust_tags = true; },
-            "notrust" => { notrust = true; seen_rust_tags = true; },
-            "rust" => { notrust = false; seen_rust_tags = true; },
-            _ => { seen_other_tags = true }
+#[deriving(Eq, PartialEq, Clone, Show)]
+struct LangString {
+    should_fail: bool,
+    no_run: bool,
+    ignore: bool,
+    notrust: bool,
+    test_harness: bool,
+}
+
+impl LangString {
+    fn all_false() -> LangString {
+        LangString {
+            should_fail: false,
+            no_run: false,
+            ignore: false,
+            notrust: false,
+            test_harness: false,
         }
     }
 
-    let notrust = notrust || (seen_other_tags && !seen_rust_tags);
+    fn parse(string: &str) -> LangString {
+        let mut seen_rust_tags = false;
+        let mut seen_other_tags = false;
+        let mut data = LangString::all_false();
+
+        let mut tokens = string.as_slice().split(|c: char|
+            !(c == '_' || c == '-' || c.is_alphanumeric())
+        );
+
+        for token in tokens {
+            match token {
+                "" => {},
+                "should_fail" => { data.should_fail = true; seen_rust_tags = true; },
+                "no_run" => { data.no_run = true; seen_rust_tags = true; },
+                "ignore" => { data.ignore = true; seen_rust_tags = true; },
+                "notrust" => { data.notrust = true; seen_rust_tags = true; },
+                "rust" => { data.notrust = false; seen_rust_tags = true; },
+                "test_harness" => { data.test_harness = true; seen_rust_tags = true; }
+                _ => { seen_other_tags = true }
+            }
+        }
+
+        data.notrust |= seen_other_tags && !seen_rust_tags;
 
-    (should_fail, no_run, ignore, notrust)
+        data
+    }
 }
 
 /// By default this markdown renderer generates anchors for each header in the
@@ -425,19 +445,32 @@ impl<'a> fmt::Show for MarkdownWithToc<'a> {
 
 #[cfg(test)]
 mod tests {
-    use super::parse_lang_string;
+    use super::LangString;
 
     #[test]
-    fn test_parse_lang_string() {
-        assert_eq!(parse_lang_string(""), (false,false,false,false))
-        assert_eq!(parse_lang_string("rust"), (false,false,false,false))
-        assert_eq!(parse_lang_string("sh"), (false,false,false,true))
-        assert_eq!(parse_lang_string("notrust"), (false,false,false,true))
-        assert_eq!(parse_lang_string("ignore"), (false,false,true,false))
-        assert_eq!(parse_lang_string("should_fail"), (true,false,false,false))
-        assert_eq!(parse_lang_string("no_run"), (false,true,false,false))
-        assert_eq!(parse_lang_string("{.no_run .example}"), (false,true,false,false))
-        assert_eq!(parse_lang_string("{.sh .should_fail}"), (true,false,false,false))
-        assert_eq!(parse_lang_string("{.example .rust}"), (false,false,false,false))
+    fn test_lang_string_parse() {
+        fn t(s: &str,
+             should_fail: bool, no_run: bool, ignore: bool, notrust: bool, test_harness: bool) {
+            assert_eq!(LangString::parse(s), LangString {
+                should_fail: should_fail,
+                no_run: no_run,
+                ignore: ignore,
+                notrust: notrust,
+                test_harness: test_harness,
+            })
+        }
+
+        t("", false,false,false,false,false);
+        t("rust", false,false,false,false,false);
+        t("sh", false,false,false,true,false);
+        t("notrust", false,false,false,true,false);
+        t("ignore", false,false,true,false,false);
+        t("should_fail", true,false,false,false,false);
+        t("no_run", false,true,false,false,false);
+        t("test_harness", false,false,false,false,true);
+        t("{.no_run .example}", false,true,false,false,false);
+        t("{.sh .should_fail}", true,false,false,false,false);
+        t("{.example .rust}", false,false,false,false,false);
+        t("{.test_harness .rust}", false,false,false,false,true);
     }
 }

branches/try2/src/librustdoc/html/static/main.css

@@ -347,7 +347,7 @@ p a:hover { text-decoration: underline; }
     margin-top: -125px;
     margin-left: -275px;
     width: 550px;
-    height: 250px;
+    height: 300px;
     border: 1px solid #bfbfbf;
 }