Can't use a dependent crate in Rust documentation tests

Question

I'm trying to write docs for a project I'm writing in Rust. One of the docs requires using regex::Regex. Here's the doc I'm trying to write:

/// Return a list of the offsets of the tokens in `s`, as a sequence of `(start, end)`
/// tuples, by splitting the string at each successive match of `regex`.
///
/// # Examples
///
/// ```
/// use rusty_nltk::tokenize::util::regexp_span_tokenize;
/// use regex::Regex;
///
/// let s = "Good muffins cost $3.88\nin New York.  Please buy me
///         two of them.\n\nThanks.";
/// let regex = regex::Regex::new(r"\s").unwrap();
/// let spans = regexp_span_tokenize(s, regex).unwrap();
/// ```

It gives me this error:

---- tokenize::util::regexp_span_tokenize_0 stdout ----
    <anon>:4:9: 4:14 error: unresolved import `regex::Regex`. Maybe a missing `extern crate regex`? [E0432]
<anon>:4     use regex::Regex;
                 ^~~~~
error: aborting due to previous error

But when I add extern crate regex;, I get this error:

---- tokenize::util::regexp_span_tokenize_0 stdout ----
    <anon>:3:9: 3:19 error: unresolved import `rusty_nltk::tokenize::util::regexp_span_tokenize`. Maybe a missing `extern crate rusty_nltk`? [E0432]
<anon>:3     use rusty_nltk::tokenize::util::regexp_span_tokenize;
                 ^~~~~~~~~~
<anon>:4:9: 4:14 error: unresolved import `regex::Regex`. Did you mean `self::regex`? [E0432]
<anon>:4     use regex::Regex;
                 ^~~~~
error: aborting due to 2 previous errors

Some relevant parts of relevant files are:

src/lib.rs:

extern crate regex;
pub mod tokenize;

src/tokenize/mod.rs:

extern crate regex;
pub mod util;

(Top of) src/tokenize/util.rs:

extern crate regex; 
use regex::Regex;

What am I doing wrong with the layout of my project?

score 9 · Accepted Answer · edited Jun 20 '20 at 09:12

From The Rust Programming Language, first edition chapter on documentation:

Here's the full algorithm rustdoc uses to preprocess examples:

Any leading #![foo] attributes are left intact as crate attributes.

Some common allow attributes are inserted, including unused_variables, unused_assignments, unused_mut, unused_attributes, and dead_code. Small examples often trigger these lints.

If the example does not contain extern crate, then extern crate <mycrate>; is inserted.

Finally, if the example does not contain fn main, the remainder of the text is wrapped in fn main() { your_code }

Point #3 is relevant here. When you have no extern crate lines, your crate is automatically added. Once you add the first extern crate, no crates will be automatically added — that includes your crate!

You will need to add extern crate lines for both regex and rusty_nltk.

I was just about to post this as an answer. I will give this the answer and add my solution as a separate answer. — erip, Dec 19 '15 at 18:48

erip · Answer 2 · 2015-12-19T22:38:10.543

After being pointed to the docs, I solved it by wrapping a main around my code with extern crates:

/// Return a list of the offsets of the tokens in `s`, as a sequence of `(start, end)`
/// tuples, by splitting the string at each successive match of `regex`.
///
/// # Examples
///
/// To return a list of spans based on whitespaces:
///
/// ```
/// extern crate regex;
/// extern crate rusty_nltk;
/// use rusty_nltk::tokenize::util::regexp_span_tokenize;
/// use regex::Regex;
///
/// fn main() {
///   let s = "Good muffins cost $3.88\nin New York.  Please buy me
///           two of them.\n\nThanks.";
///   let regex = Regex::new(r"\s").unwrap();
///   let spans = regexp_span_tokenize(s, &regex);
/// }
/// ```

I decided to change my doc style to include mains for all examples, but if this isn't your style, you can add # before code to hide it from docs.

Can't use a dependent crate in Rust documentation tests

src/lib.rs:

src/tokenize/mod.rs:

(Top of) src/tokenize/util.rs:

2 Answers2