From 71cab0410f411c78dfe297bec5d35ad5a9e09d35 Mon Sep 17 00:00:00 2001
From: Steven Fackler <sfackler@gmail.com>
Date: Sat, 8 Mar 2014 19:39:01 -0800
Subject: [PATCH] Add an option to not run rustdoc blocks

This is useful for code that would be expensive to run or has some kind
of external dependency (e.g. a database or server).
---
 src/doc/rustdoc.md              | 13 +++++++++++--
 src/librustdoc/html/markdown.rs | 11 ++++++-----
 src/librustdoc/test.rs          |  9 ++++++---
 3 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/src/doc/rustdoc.md b/src/doc/rustdoc.md
index 3c04d867df9..545cafd7f31 100644
--- a/src/doc/rustdoc.md
+++ b/src/doc/rustdoc.md
@@ -117,8 +117,8 @@ code block.
     // This is a testable code block (4-space indent)
 ~~~
 
-In addition to the `ignore` directive, you can specify that the test's execution
-should fail with the `should_fail` directive.
+You can specify that the test's execution should fail with the `should_fail`
+directive.
 
 ~~~
 ```should_fail
@@ -126,6 +126,15 @@ should fail with the `should_fail` directive.
 ```
 ~~~
 
+You can specify that the code block should be compiled but not run with the
+`no_run` directive.
+
+~~~
+```no_run
+// This code will be compiled but not executed
+```
+~~~
+
 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
diff --git a/src/librustdoc/html/markdown.rs b/src/librustdoc/html/markdown.rs
index aca20331f0a..19a28931a8a 100644
--- a/src/librustdoc/html/markdown.rs
+++ b/src/librustdoc/html/markdown.rs
@@ -245,14 +245,15 @@ pub fn find_testable_code(doc: &str, tests: &mut ::test::Collector) {
     extern fn block(_ob: *buf, text: *buf, lang: *buf, opaque: *libc::c_void) {
         unsafe {
             if text.is_null() { return }
-            let (shouldfail, ignore) = if lang.is_null() {
-                (false, false)
+            let (should_fail, no_run, ignore) = if lang.is_null() {
+                (false, false, false)
             } else {
                 vec::raw::buf_as_slice((*lang).data,
                                        (*lang).size as uint, |lang| {
                     let s = str::from_utf8(lang).unwrap();
-                    (s.contains("should_fail"), s.contains("ignore") ||
-                                                s.contains("notrust"))
+                    (s.contains("should_fail"),
+                     s.contains("no_run"),
+                     s.contains("ignore") || s.contains("notrust"))
                 })
             };
             if ignore { return }
@@ -261,7 +262,7 @@ pub fn find_testable_code(doc: &str, tests: &mut ::test::Collector) {
                 let text = str::from_utf8(text).unwrap();
                 let mut lines = text.lines().map(|l| stripped_filtered_line(l).unwrap_or(l));
                 let text = lines.to_owned_vec().connect("\n");
-                tests.add_test(text, shouldfail);
+                tests.add_test(text, should_fail, no_run);
             })
         }
     }
diff --git a/src/librustdoc/test.rs b/src/librustdoc/test.rs
index f34ce016f28..5edc24c6066 100644
--- a/src/librustdoc/test.rs
+++ b/src/librustdoc/test.rs
@@ -98,7 +98,8 @@ pub fn run(input: &str, matches: &getopts::Matches) -> int {
     0
 }
 
-fn runtest(test: &str, cratename: &str, libs: HashSet<Path>, should_fail: bool) {
+fn runtest(test: &str, cratename: &str, libs: HashSet<Path>, should_fail: bool,
+           no_run: bool) {
     let test = maketest(test, cratename);
     let parsesess = parse::new_parse_sess();
     let input = driver::StrInput(test);
@@ -152,6 +153,8 @@ fn runtest(test: &str, cratename: &str, libs: HashSet<Path>, should_fail: bool)
     let cfg = driver::build_configuration(sess);
     driver::compile_input(sess, cfg, &input, &out, &None);
 
+    if no_run { return }
+
     // Run the code!
     let exe = outdir.path().join("rust_out");
     let out = Process::output(exe.as_str().unwrap(), []);
@@ -203,7 +206,7 @@ pub struct Collector {
 }
 
 impl Collector {
-    pub fn add_test(&mut self, test: &str, should_fail: bool) {
+    pub fn add_test(&mut self, test: &str, should_fail: bool, no_run: bool) {
         let test = test.to_owned();
         let name = format!("{}_{}", self.names.connect("::"), self.cnt);
         self.cnt += 1;
@@ -218,7 +221,7 @@ impl Collector {
                 should_fail: false, // compiler failures are test failures
             },
             testfn: testing::DynTestFn(proc() {
-                runtest(test, cratename, libs, should_fail);
+                runtest(test, cratename, libs, should_fail, no_run);
             }),
         });
     }