文档示例中存在未解决的导入问题。

Question

我在为我的库修复文档示例中的错误时遇到了困难。我的crate的文件结构如下：bignum

.
|-- Cargo.lock
|-- Cargo.toml
|-- examples
|   |-- dat
|   |   `-- euler_13.dat
|   |-- debug.rs
|   `-- euler_13.rs
|-- README.md
|-- src
|   |-- error.rs
|   |-- inits.rs
|   `-- lib.rs

在我的示例中，我的标题将类似于

// euler_13.rs 
extern crate bignum;
use bignum::inits::Zero;

// ...

这个编译并且运行良好，但是现在当我在lib.rs文档中写一个例子的时候，我似乎无法导入bignum::inits::Zero

//lib.rs
//...

impl BigNum {

    //...


    /// Constructs a ...
    ///
    /// # Examples
    ///
    /// ```
    /// extern crate bignum;
    /// use bignum::inits::Zero;
    ///
    /// let a = bignum::BigNum::new(Zero::zero());
    /// ```
    ///
    pub fn new(base: BigNum) -> BigNum {
        // ...
    }

当我运行cargo test时，我收到了这个错误

     Running target/debug/lib-fe3dd7a75a504b04

running 3 tests
test crate_from_u32 ... ok
test create_from_string ... ok
test adding_no_carry ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured

   Doc-tests bignum

running 1 test
test new_0 ... FAILED

failures:

---- new_0 stdout ----
    <anon>:3:9: 3:15 error: unresolved import `self::bignum::inits::Zero`. Did you mean `self::self::bignum::inits`?
<anon>:3     use self::bignum::inits::Zero;
                 ^~~~~~
error: aborting due to previous error
thread 'new_0' panicked at 'Box<Any>', /home/rustbuild/src/rust-buildbot/slave/stable-dist-rustc-linux/build/src/libsyntax/diagnostic.rs:192



failures:
    new_0

我看到了这个问题，但它处理的是从相同文件导入模块仍需要顶层范围。然而，在这里，我仍然使用bignum::指定了顶层范围。

因此，虽然导入bignum::inits::Zero对于我的所有测试和示例都有效，但对于我的文档却无效。为什么会这样？我尝试在前面添加self::，但仍然收到相同的错误。如果我将示例更改为

extern crate bignum;

let a = bignum::BigNum::new(bignum::inits::Zero::zero());

它编译得很好。 但是，我该如何正确导入我的模块？

- Syntactic Fructose

---

@Shepmaster，虽然我认为这些是不同的问题，但另一个答案实际上解决了我的问题。我认为这是因为我的问题在于，在# Examples中，extern create bignum是隐含的，所以再次执行会创建错误。我提交了一个问题，建议更改此类错误的输出。 - Syntactic Fructose

当然，我会继续做那件事。 - Syntactic Fructose

离题：当我建议一个重复的问题时，是否有可能不删除我的评论？写完一条消息后看到它在一段时间后消失是非常令人沮丧的。这已经是第二次发生了。链接 - mdup

据我所知，如果接受了重复建议，那个来自建议的评论会自动删除。我的建议是将其拆分为两个评论或者如果只是建议，则不要使用关闭链接。 - Shepmaster

@Shepmaster 好的，下次会这么做。顺便说一下，我从未使用过关闭投票（尚不能获得足够的声望）。如果问题被取消重复，恢复评论将是很好的。 - mdup

如果您没有使用关闭链接来建议重复，我对此行为感到惊讶。 值得在 [元] 上发一个问题询问。 - Shepmaster

Answer 1

我认为问题源于这个文档测试的有用特性：

rustdoc将自动为您的代码添加一个main()包装器，并放在正确的位置。

如果按照链接中的规则进行操作，您最终会编译出如下的代码：

fn main() {
   extern crate bignum;
   use bignum::inits::Zero;

   let a = bignum::BigNum::new(Zero::zero());
}

正如第一个错误信息所建议的那样，您确实需要将其称为self::bignum。不幸的是，由于Rust问题23314的存在，目前这样做是行不通的。

- Shepmaster

---

啊，这就是为什么它不起作用的解释。 - Syntactic Fructose

Answer 2

因此，生成此错误的原因在于文档示例隐式使用了extern crate bignum，这意味着我不需要显式地告诉示例我将使用bignum。

这是有道理的，因为在文档级别上，示例展示了你的箱子特定部分的功能应该如何工作，所以你将无论如何使用bignum。cargo识别到这一点并为您导入bignum。示例应该像下面这样：

//lib.rs
//...

impl BigNum {

    //...


    /// Constructs a ...
    ///
    /// # Examples
    ///
    /// ```
    /// use bignum::inits::Zero;
    ///
    /// let a = bignum::BigNum::new(Zero::zero());
    /// ```
    ///
    pub fn new(base: BigNum) -> BigNum {
        // ...
    }
}

- Syntactic Fructose