Ошибка использования локальных модулей в документации тестов

Question

Я играю с небольшим ящиком для создания 2D шума. Вот упрощенный фрагмент моего файла "lib.rs":

pub mod my_math {
    pub struct Vec2<T> {
        ...
    }
    ...
}
pub mod my_noise {
    use num::Float;
    use std::num::Wrapping;
    use my_math::*;

    /// Gets pseudo-random noise based on a seed vector.
    /// 
    /// # Examples
    /// 
    /// ```
    /// use my_math::Vec2;
    /// 
    /// let v_seed = Vec2::<f32>::new_values(4.134, -23.141);
    /// let noise_val = get_noise_white(&v_seed);
    /// 
    /// assert!(noise_val >= 0.0);
    /// assert!(noise_val <= 1.0);
    /// ```
    pub fn get_noise_white(seed: &Vec2<f32>) -> f32 {
        ...
    }
}

Однако, когда я запускаю тестирование груза, я получаю следующую ошибку:

---- my_noise:: get_noise_white_0 stdout ----

: 3: 9: 3:16 ошибка: неразрешенный импорт my_math::Vec2, Может быть пропавший extern crate my_math?

: 3 use my_math:: Vec2;

Я также пробовал другие формы use заявление в комментарии к документу, в том числе use my_math::*; а также use self::my_math::*;, Если я удаляю строку целиком, то получаю ошибку, Vec2 не определено

Как правильно это сделать?

Answer 1

Вы должны указать имя верхнего уровня вашего ящика (назовем его mylib):

use mylib::my_math::Vec2;

Обоснование заключается в том, что ваш пример документа должен использоваться клиентом вашей библиотеки как есть. Если вы поставите себя на их место, они заберут вашу библиотеку (обычно грузом, но это не имеет значения), а затем поставят extern crate mylib на их верхнем уровне lib.rs/main.rs. Затем, чтобы использовать части вашей библиотеки, им нужно будет указать полное имя, чтобы использовать его дочерние элементы.

И это именно то, что вы должны сделать в своем комментарии, проверенном ржавчиной.

Кроме того, я думаю, что стоит упомянуть соответствующую часть книги Rust " Документация как тесты", которая объясняет некоторые незначительные изменения, примененные к фрагментам кода документа. Один из них является:

Если пример не содержит extern crate, затем extern crate <mycrate>; вставлен.