文档示例中未解决的导入

Posted 2023-02-19

【中文标题】文档示例中未解决的导入

【英文标题】：Unresolved import in documentation example

【发布时间】：2015-10-16 18:19:09

【问题描述】：

我在为我的库的文档示例中修复错误时遇到了困难。我有像我的箱子一样的文件结构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

我见过this 问题，但这涉及从仍需要***范围的同一文件中导入模块。但是在这里我仍然使用bignum:: 指定***范围。

因此，虽然导入 bignum::inits::Zero 适用于我的所有测试和示例，但它不适用于我的文档。这是为什么？我尝试在前面附加 self:: 并收到相同的错误。如果我将文档示例更改为

extern crate bignum;

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

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

【问题讨论】：

@Shepmaster 所以虽然我认为这些是不同的问题，但另一个答案确实解决了我的问题。我认为这是因为我的问题是在# Examples 中，extern create bignum 是隐式的，所以再次这样做会产生错误。我提交了 issue 并建议更改此类错误的错误输出

当然，我会继续这样做

题外话：当我建议复制时，是否可以不删除我的 cmets？编写一条消息只是看到它在一段时间后消失是非常令人沮丧的。这是second time 它发生了。

@mdup AFAIK，如果重复的建议被接受，来自该建议的评论将被自动删除。我唯一的建议是将它分成两个 cmets，或者如果您只是建议，则不要使用关闭链接。

@Shepmaster 好的，下次会这样做。顺便说一句，我从未使用过近距离投票（还没有足够的代表）。如果在问题不重复后恢复评论会很好。

【参考方案1】：

我认为问题源于这个useful feature of the doc tests：

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

如果您在链接中应用规则，您最终会编译如下代码：

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

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

您确实需要将其称为self::bignum，正如第一条错误消息所暗示的那样。不幸的是，由于Rust issue 23314，这目前不起作用。

【讨论】：

啊，这就是为什么它不起作用的原因。

【参考方案2】：

因此，生成此错误的原因归结为 extern crate bignum 被文档示例隐式使用，这意味着我不需要明确告诉示例我将使用 bignum。

这是有道理的，因为在文档级别，示例显示了您的 crate 特定部分的功能应该如何工作，因此无论如何您都将使用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 
        // ...