auto merge of #11185 : huonw/rust/doc-ignore, r=cmr

Currently any line starting with `#` is filtered from the output,
including line like `#[deriving]`; this patch makes it so lines are only
filtered when followed by a space similar to the current behaviour of
the tutorial/manual tester.

doc/rustdoc.md

@@ -132,9 +132,10 @@ specifiers that can be used to dictate how a code block is tested:
 ~~~
 
 Rustdoc also supplies some extra sugar for helping with some tedious
-documentation examples. If a line is prefixed with a `#` character, then the
+documentation examples. If a line is prefixed with `# `, then the line
-line will not show up in the HTML documentation, but it will be used when
+will not show up in the HTML documentation, but it will be used when
-testing the code block.
+testing the code block (NB. the space after the `#` is required, so
+that one can still write things like `#[deriving(Eq)]`).
 
 ~~~
 ```rust

src/librustdoc/html/markdown.rs

@@ -94,15 +94,26 @@ extern {
 
 }
 
+/// Returns Some(code) if `s` is a line that should be stripped from
+/// documentation but used in example code. `code` is the portion of
+/// `s` that should be used in tests. (None for lines that should be
+/// left as-is.)
+fn stripped_filtered_line<'a>(s: &'a str) -> Option<&'a str> {
+    let trimmed = s.trim();
+    if trimmed.starts_with("# ") {
+        Some(trimmed.slice_from(2))
+    } else {
+        None
+    }
+}
+
 pub fn render(w: &mut io::Writer, s: &str) {
     extern fn block(ob: *buf, text: *buf, lang: *buf, opaque: *libc::c_void) {
         unsafe {
             let my_opaque: &my_opaque = cast::transmute(opaque);
             vec::raw::buf_as_slice((*text).data, (*text).size as uint, |text| {
                 let text = str::from_utf8(text);
-                let mut lines = text.lines().filter(|l| {
+                let mut lines = text.lines().filter(|l| stripped_filtered_line(*l).is_none());
-                    !l.trim().starts_with("#")
-                });
                 let text = lines.to_owned_vec().connect("\n");
 
                 let buf = buf {
@@ -169,7 +180,7 @@ pub fn find_testable_code(doc: &str, tests: &mut ::test::Collector) {
             vec::raw::buf_as_slice((*text).data, (*text).size as uint, |text| {
                 let tests: &mut ::test::Collector = intrinsics::transmute(opaque);
                 let text = str::from_utf8(text);
-                let mut lines = text.lines().map(|l| l.trim_chars(&'#'));
+                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, ignore, shouldfail);
             })

src/librustdoc/test.rs

@@ -173,6 +173,7 @@ impl Collector {
         let libs = self.libs.borrow();
         let libs = (*libs.get()).clone();
         let cratename = self.cratename.to_owned();
+        debug!("Creating test {}: {}", name, test);
         self.tests.push(test::TestDescAndFn {
             desc: test::TestDesc {
                 name: test::DynTestName(name),

src/test/run-make/rustdoc-hidden-line/Makefile

@@ -0,0 +1,7 @@
+-include ../tools.mk
+
+all:
+	$(RUSTDOC) --test foo.rs
+	$(RUSTDOC) -w html -o $(TMPDIR)/doc foo.rs
+	cp verify.sh $(TMPDIR)
+	$(call RUN,verify.sh) $(TMPDIR)

src/test/run-make/rustdoc-hidden-line/foo.rs

@@ -0,0 +1,22 @@
+#[crate_id="foo#0.1"];
+
+/// The '# ' lines should be removed from the output, but the #[deriving] should be
+/// retained.
+///
+/// ```rust
+/// mod to_make_deriving_work { // FIXME #4913
+///
+/// # #[deriving(Eq)] // invisible
+/// # struct Foo; // invisible
+///
+/// #[deriving(Eq)] // Bar
+/// struct Bar(Foo);
+///
+/// fn test() {
+///     let x = Bar(Foo);
+///     assert!(x == x); // check that the derivings worked
+/// }
+///
+/// }
+/// ```
+pub fn foo() {}

src/test/run-make/rustdoc-hidden-line/verify.sh

@@ -0,0 +1,8 @@
+#!/bin/sh
+
+file="$1/doc/foo/fn.foo.html"
+
+grep -v 'invisible' $file &&
+grep '#\[deriving(Eq)\] // Bar' $file
+
+exit $?