Início / coding / Perguntas / 78043945
Accepted
ViperZer0
Asked: 2024-02-23 04:50:03 +0800 CST

Os exemplos de documentação exigem que a estrutura relevante seja importada, mas apenas durante a execução de testes. Este é o comportamento pretendido?

  • 772

Eu tenho uma estrutura muito simples e uma new()implementação para essa estrutura.

    pub struct Square {
        rank: usize,
        file: usize,
    }

    impl Square {
        /// # Examples
        /// ```
        /// Square::new(0,0); //The square A1.
        /// ```
    }

Além disso, tenho alguns testes (esses testes chamam Square::new(), embora não sejam testes para essa função). Quando executo cargo test, recebo o seguinte erro para o código no meu exemplo de documentação:

uso de tipo não declarado Square. Considere importar esta estrutura.

Curiosamente, esse problema não acontece quando executo cargo buildou cargo doc.

O problema desaparece quando importo a estrutura conforme recomendado pelo compilador. No entanto, não parece que isso seja algo que eu deva fazer, já que (presumo) os exemplos devem ser tão concisos quanto possível. Observando o código-fonte do String::new(), a documentação de exemplo consiste em uma linha de código, sem necessidade de importação. O código-fonte inclui env::argsuma importação de std::env.

Este é o comportamento pretendido? Isso é um inseto?

rust

1 respostas

  1. Best Answer

    Este é o comportamento pretendido. Doctests são uma ferramenta poderosa para documentar sua API e testar sua implementação ao mesmo tempo. Para fazer isso, eles devem compilar com sucesso.

    Porém, sendo documentação, os doctests também precisam ser curtos e concisos. Portanto, se você acredita que algum código não é necessário para entender o exemplo (mas ainda é necessário que esteja lá para que o doctest seja compilado), você pode ocultar esta linha acrescentando a a #ela:

    /// # Examples
/// ```
/// # use crate::Square;
/// Square::new(0,0); //The square A1.
/// ```
    • 2

relate perguntas