It's too easy to forget the `rust` tag to test something.
Closes #11698
## Defining tests
-Rust documentation currently uses the markdown format, and code blocks can refer
-to any piece of code-related documentation, which isn't always rust. Because of
-this, only code blocks with the language of "rust" will be considered for
-testing.
+Rust documentation currently uses the markdown format, and rustdoc treats all
+code blocks as testable-by-default. In order to not run a test over a block of
+code, the `ignore` string can be added to the three-backtick form of markdown
+code block.
~~~
-```rust
+```
// This is a testable code block
```
-```
+```ignore
// This is not a testable code block
```
- // This is not a testable code block (4-space indent)
+ // This is a testable code block (4-space indent)
~~~
-In addition to only testing "rust"-language code blocks, there are additional
-specifiers that can be used to dictate how a code block is tested:
+In addition to the `ignore` directive, you can specify that the test's execution
+should fail with the `should_fail` directive.
~~~
-```rust,ignore
-// This code block is ignored by rustdoc, but is passed through to the test
-// harness
-```
-
-```rust,should_fail
-// This code block is expected to generate a failure
+```should_fail
+// This code block is expected to generate a failure when run
```
~~~
# the doc-generating tool. In order to display them anyway in this particular
# case, the character following the leading '#' is not a usual space like in
# these first five lines but a non breakable one.
-#
+#
# // showing 'fib' in this documentation would just be tedious and detracts from
# // what's actualy being documented.
# fn fib(n: int) { n + 2 }
// See what's possible when running tests
rustdoc --test lib.rs --test-args '--help'
-
-// Run all ignored tests
-rustdoc --test lib.rs --test-args '--ignored'
~~~
When testing a library, code examples will often show how functions are used,
Arrays are enclosed in square brackets ([ ... ]) and objects in curly brackets ({ ... }).
A simple JSON document encoding a person, his/her age, address and phone numbers could look like:
-```
+```ignore
{
"FirstName": "John",
"LastName": "Doe",
/// As an example, the summary with 5-number-summary `(min=15, q1=17, med=20, q3=24, max=31)` might
/// display as:
///
-/// ~~~~
+/// ~~~~ignore
/// 10 | [--****#******----------] | 40
/// ~~~~
///
/// The above code will print:
///
-/// ```
+/// ```ignore
/// /media/pictures/kittens.jpg
/// /media/pictures/puppies.jpg
/// ```
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() || lang.is_null() { return }
- let (test, shouldfail, ignore) =
+ if text.is_null() { return }
+ let (shouldfail, ignore) = if lang.is_null() {
+ (false, false)
+ } else {
vec::raw::buf_as_slice((*lang).data,
(*lang).size as uint, |lang| {
let s = str::from_utf8(lang).unwrap();
- (s.contains("rust"), s.contains("should_fail"),
- s.contains("ignore"))
- });
- if !test { return }
+ (s.contains("should_fail"), s.contains("ignore"))
+ })
+ };
+ if ignore { return }
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).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, ignore, shouldfail);
+ tests.add_test(text, shouldfail);
})
}
}
0
}
-fn runtest(test: &str, cratename: &str, libs: HashSet<Path>) {
+fn runtest(test: &str, cratename: &str, libs: HashSet<Path>, should_fail: bool) {
let test = maketest(test, cratename);
let parsesess = parse::new_parse_sess();
let input = driver::StrInput(test);
match out {
Err(e) => fail!("couldn't run the test: {}", e),
Ok(out) => {
- if !out.status.success() {
- fail!("test executable failed:\n{}",
- str::from_utf8(out.error));
+ if should_fail && out.status.success() {
+ fail!("test executable succeeded when it should have failed");
+ } else if !should_fail && !out.status.success() {
+ fail!("test executable failed:\n{}", str::from_utf8(out.error));
}
}
}
}
impl Collector {
- pub fn add_test(&mut self, test: &str, ignore: bool, should_fail: bool) {
+ pub fn add_test(&mut self, test: &str, should_fail: bool) {
let test = test.to_owned();
let name = format!("{}_{}", self.names.connect("::"), self.cnt);
self.cnt += 1;
self.tests.push(test::TestDescAndFn {
desc: test::TestDesc {
name: test::DynTestName(name),
- ignore: ignore,
- should_fail: should_fail,
+ ignore: false,
+ should_fail: false, // compiler failures are test failures
},
testfn: test::DynTestFn(proc() {
- runtest(test, cratename, libs);
+ runtest(test, cratename, libs, should_fail);
}),
});
}
//! let (port, chan) = Chan::new();
//! spawn(proc() {
//! chan.send(10);
-//! })
+//! });
//! assert_eq!(port.recv(), 10);
//!
//! // Create a shared channel which can be sent along from many tasks
leverage named parameters. Named parameters are listed at the end of the
argument list and have the syntax:
-```
+```ignore
identifier '=' expression
```
is used (the type's rust-representation is printed). For example, this is an
invalid format string:
-```
+```ignore
{0:d} {0:s}
```
illegal to reference an argument as such. For example, this is another invalid
format string:
-```
+```ignore
{:.*s} {0:u}
```
The select method is a switch over a `&str` parameter, and the parameter *must*
be of the type `&str`. An example of the syntax is:
-```
+```ignore
{0, select, male{...} female{...} other{...}}
```
parameter *must* be a `uint`. A plural method in its full glory can be specified
as:
-```
+```ignore
{0, plural, offset=1 =1{...} two{...} many{...} other{...}}
```
meaning that arguments are surrounded by `{}` instead of the C-like `%`. The
actual grammar for the formatting syntax is:
-```
+```ignore
format_string := <text> [ format <text> ] *
format := '{' [ argument ] [ ':' format_spec ] [ ',' function_spec ] '}'
argument := integer | identifier
/// # Example
///
/// ```
-/// let reader = PortReader::new(port);
+/// use std::io::PortReader;
+///
+/// let (port, chan) = Chan::new();
+/// # drop(chan);
+/// let mut reader = PortReader::new(port);
///
/// let mut buf = ~[0u8, ..100];
/// match reader.read(buf) {
-/// Some(nread) => println!("Read {} bytes", nread),
-/// None => println!("At the end of the stream!")
+/// Ok(nread) => println!("Read {} bytes", nread),
+/// Err(e) => println!("read error: {}", e),
/// }
/// ```
pub struct PortReader {
/// # Example
///
/// ```
-/// let writer = ChanWriter::new(chan);
+/// # #[allow(unused_must_use)];
+/// use std::io::ChanWriter;
+///
+/// let (port, chan) = Chan::new();
+/// # drop(port);
+/// let mut writer = ChanWriter::new(chan);
/// writer.write("hello, world".as_bytes());
/// ```
pub struct ChanWriter {
/// # Example
///
/// ```
+ /// # fn main() {}
+ /// # fn foo() {
+ /// # #[allow(unused_must_use)];
/// use std::io::net::unix::UnixListener;
- /// use std::io::Listener;
+ /// use std::io::{Listener, Acceptor};
///
- /// let server = Path::new("path/to/my/socket");
- /// let mut stream = UnixListener::bind(&server);
- /// for client in stream.incoming() {
- /// let mut client = client;
+ /// let server = Path::new("/path/to/my/socket");
+ /// let stream = UnixListener::bind(&server);
+ /// for mut client in stream.listen().incoming() {
/// client.write([1, 2, 3, 4]);
/// }
+ /// # }
/// ```
pub fn bind<P: ToCStr>(path: &P) -> IoResult<UnixListener> {
LocalIo::maybe_raise(|io| {
/// Given a struct `S` that includes a type parameter `T`
/// but does not actually *reference* that type parameter:
///
- /// ```
+ /// ```ignore
+ /// use std::cast;
+ ///
/// struct S<T> { x: *() }
/// fn get<T>(s: &S<T>) -> T {
/// unsafe {
/// but does not actually *reference* that type parameter:
///
/// ```
+ /// use std::cast;
+ ///
/// struct S<T> { x: *() }
/// fn get<T>(s: &S<T>, v: T) {
/// unsafe {
/// "interior" mutability:
///
/// ```
- /// struct Cell<T> { priv value: T }
+ /// pub struct Cell<T> { priv value: T }
+ /// # fn main() {}
/// ```
///
/// The type system would infer that `value` is only read here and
`RUST_LOG` environment variable. The value of this environment variable is a
comma-separated list of logging directives. A logging directive is of the form:
-```
+```ignore
path::to::module=log_level
```
Some examples of valid values of `RUST_LOG` are:
-```
+```ignore
hello // turns on all logging for the 'hello' module
info // turns on all info logging
hello=debug // turns on debug logging for 'hello'
/// Returns the integer remainder after division, satisfying:
///
/// ```
+ /// # let n = 1;
+ /// # let d = 2;
/// assert!((n / d) * d + (n % d) == n)
/// ```
///
/// # Examples
///
/// ```
- /// assert!(( 8).div_floor( 3) == 2);
- /// assert!(( 8).div_floor(-3) == -3);
- /// assert!((-8).div_floor( 3) == -3);
- /// assert!((-8).div_floor(-3) == 2);
- ///
- /// assert!(( 1).div_floor( 2) == 0);
- /// assert!(( 1).div_floor(-2) == -1);
- /// assert!((-1).div_floor( 2) == -1);
- /// assert!((-1).div_floor(-2) == 0);
+ /// assert!(( 8i).div_floor(& 3) == 2);
+ /// assert!(( 8i).div_floor(&-3) == -3);
+ /// assert!((-8i).div_floor(& 3) == -3);
+ /// assert!((-8i).div_floor(&-3) == 2);
+ ///
+ /// assert!(( 1i).div_floor(& 2) == 0);
+ /// assert!(( 1i).div_floor(&-2) == -1);
+ /// assert!((-1i).div_floor(& 2) == -1);
+ /// assert!((-1i).div_floor(&-2) == 0);
/// ```
///
#[inline]
/// Integer modulo, satisfying:
///
/// ```
- /// assert!(n.div_floor(d) * d + n.mod_floor(d) == n)
+ /// # let n = 1i; let d = 1i;
+ /// assert!(n.div_floor(&d) * d + n.mod_floor(&d) == n)
/// ```
///
/// # Examples
///
/// ```
- /// assert!(( 8).mod_floor( 3) == 2);
- /// assert!(( 8).mod_floor(-3) == -1);
- /// assert!((-8).mod_floor( 3) == 1);
- /// assert!((-8).mod_floor(-3) == -2);
- ///
- /// assert!(( 1).mod_floor( 2) == 1);
- /// assert!(( 1).mod_floor(-2) == -1);
- /// assert!((-1).mod_floor( 2) == 1);
- /// assert!((-1).mod_floor(-2) == -1);
+ /// assert!(( 8i).mod_floor(& 3) == 2);
+ /// assert!(( 8i).mod_floor(&-3) == -1);
+ /// assert!((-8i).mod_floor(& 3) == 1);
+ /// assert!((-8i).mod_floor(&-3) == -2);
+ ///
+ /// assert!(( 1i).mod_floor(& 2) == 1);
+ /// assert!(( 1i).mod_floor(&-2) == -1);
+ /// assert!((-1i).mod_floor(& 2) == 1);
+ /// assert!((-1i).mod_floor(&-2) == -1);
/// ```
///
#[inline]
///
/// # Laws
///
- /// ~~~
+ /// ~~~ignore
/// a + 0 = a ∀ a ∈ Self
/// 0 + a = a ∀ a ∈ Self
/// ~~~
///
/// # Laws
///
- /// ~~~
+ /// ~~~ignore
/// a * 1 = a ∀ a ∈ Self
/// 1 * a = a ∀ a ∈ Self
/// ~~~
/// # Example
///
/// ```
+/// use std::num;
+///
/// let twenty: f32 = num::cast(0x14).unwrap();
/// assert_eq!(twenty, 20f32);
/// ```
///
/// The density function of this distribution is
///
-/// ```
+/// ```ignore
/// f(x) = x^(k - 1) * exp(-x / θ) / (Γ(k) * θ^k)
/// ```
///
///
/// ## Output
///
- /// ```
+ /// ```ignore
/// 0: 中
/// 3: 华
/// 6: V
*
* ```
* spawn(proc() {
- * log(error, "Hello, World!");
+ * println!("Hello, World!");
* })
* ```
*/
# Example
- ```
+```
+use std::unstable::finally::Finally;
+# fn always_run_this() {}
+
(|| {
- ...
+ // ...
}).finally(|| {
always_run_this();
})
- ```
+```
*/
use ops::Drop;
* # Example
*
* ```
+ * use std::unstable::finally::try_finally;
+ *
* struct State<'a> { buffer: &'a mut [u8], len: uint }
+ * # let mut buf = [];
* let mut state = State { buffer: buf, len: 0 };
* try_finally(
* &mut state, (),
* |state, ()| {
* // use state.buffer, state.len
- * }
+ * },
* |state| {
* // use state.buffer, state.len to cleanup
* })
*
* Equivalent to:
*
- * ```
+ * ```ignore
* if self.len() == 0 { return None }
* let head = &self[0];
* *self = self.slice_from(1);
*
* Equivalent to:
*
- * ```
+ * ```ignore
* if self.len() == 0 { return None; }
* let tail = &self[self.len() - 1];
* *self = self.slice_to(self.len() - 1);
*
* Equivalent to:
*
- * ```
+ * ```ignore
* if self.len() == 0 { return None; }
* let head = &mut self[0];
* *self = self.mut_slice_from(1);
*
* Equivalent to:
*
- * ```
+ * ```ignore
* if self.len() == 0 { return None; }
* let tail = &mut self[self.len() - 1];
* *self = self.mut_slice_to(self.len() - 1);
For example, a type like:
+```ignore
#[deriving(Encodable, Decodable)]
struct Node {id: uint}
+```
would generate two implementations like:
Other interesting scenarios are whe the item has type parameters or
references other non-built-in types. A type definition like:
+```ignore
#[deriving(Encodable, Decodable)]
struct spanned<T> {node: T, span: Span}
+```
would yield functions like:
+```ignore
impl<
S: Encoder,
T: Encodable<S>
})
}
}
+```
*/
use ast::{MetaItem, Item, Expr, MutMutable};
an identifier in the source code. For example, the `x`s in the
following snippet
-~~~
+~~~ignore
struct A { x : int }
struct B(int);
The following simplified `Eq` is used for in-code examples:
-~~~
+~~~ignore
trait Eq {
fn eq(&self, other: &Self);
}
When generating the `expr` for the `A` impl, the `SubstructureFields` is
-~~~
+~~~ignore
Struct(~[FieldInfo {
span: <span of x>
name: Some(<ident of x>),
For the `B` impl, called with `B(a)` and `B(b)`,
-~~~
+~~~ignore
Struct(~[FieldInfo {
span: <span of `int`>,
name: None,
When generating the `expr` for a call with `self == C0(a)` and `other
== C0(b)`, the SubstructureFields is
-~~~
+~~~ignore
EnumMatching(0, <ast::Variant for C0>,
~[FieldInfo {
span: <span of int>
For `C1 {x}` and `C1 {x}`,
-~~~
+~~~ignore
EnumMatching(1, <ast::Variant for C1>,
~[FieldInfo {
span: <span of x>
For `C0(a)` and `C1 {x}` ,
-~~~
+~~~ignore
EnumNonMatching(~[(0, <ast::Variant for B0>,
~[(<span of int>, None, <expr for &a>)]),
(1, <ast::Variant for B1>,
A static method on the above would result in,
-~~~~
+~~~~ignore
StaticStruct(<ast::StructDef of A>, Named(~[(<ident of x>, <span of x>)]))
StaticStruct(<ast::StructDef of B>, Unnamed(~[<span of x>]))
* Given that we are deriving a trait `Tr` for a type `T<'a, ...,
* 'z, A, ..., Z>`, creates an impl like:
*
+ * ```ignore
* impl<'a, ..., 'z, A:Tr B1 B2, ..., Z: Tr B1 B2> Tr for T<A, ..., Z> { ... }
+ * ```
*
* where B1, B2, ... are the bounds given by `bounds_paths`.'
*
}
/**
- ~~~
+ ~~~ignore
#[deriving(Eq)]
struct A { x: int, y: int }
}
/**
- ~~~
+ ~~~ignore
#[deriving(Eq)]
enum A {
A1
/**
Creates the nested matches for an enum definition recursively, i.e.
- ~~~
+ ~~~ignore
match self {
Variant1 => match other { Variant1 => matching, Variant2 => nonmatching, ... },
Variant2 => match other { Variant1 => nonmatching, Variant2 => matching, ... },
Call the method that is being derived on all the fields, and then
process the collected results. i.e.
-~~~
+~~~ignore
f(cx, span, ~[self_1.method(__arg_1_1, __arg_2_1),
self_2.method(__arg_1_2, __arg_2_2)])
~~~
projects / rust.git / commitdiff