Rust
선적 서류 비치

소개

통사론

• /// 외부 문서 주석 (아래 항목에 적용)

• //! 내부 문서 주석 (둘러싼 항목에 적용)

• cargo doc #이 라이브러리 상자에 대한 문서를 생성합니다.

• cargo doc --open #이 라이브러리 상자 및 공개 브라우저에 대한 문서를 생성합니다.

• cargo doc -p CRATE # 지정된 크레이트에 대해서만 문서를 생성합니다.

• cargo doc --no-deps #이 라이브러리에 대한 문서를 생성하며 종속성은 없습니다.

• cargo test # 단위 테스트 및 문서 테스트를 실행합니다.

비고

문서의 보풀

가능한 모든 항목을 문서화하려면 missing_docs 링크를 사용하여 컴파일러에서 경고 / 오류를 수신 할 수 있습니다. 라이브러리 전체에 경고를 받으려면 lib.rs 파일에 다음 속성을 lib.rs 하십시오.

#![warn(missing_docs)]

이 lint를 사용하여 누락 된 문서에 대한 오류를 수신 할 수도 있습니다.

#![deny(missing_docs)]

기본적으로 missing_docs 가 허용되지만이 속성을 사용하여 명시 적으로 허용 할 수 있습니다.

#![allow(missing_docs)]

이는 하나의 모듈을 하나의 모듈에 대해 누락 된 문서를 허용하지만 다른 모든 파일에서는 거부하는 데 유용 할 수 있습니다.

문서 코멘트

Rust는 내부 문서 주석과 외부 문서 주석의 두 가지 유형의 문서 주석을 제공합니다. 각각의 예가 아래에 나와 있습니다.

내부 문서 주석

mod foo {
    //! Inner documentation comments go *inside* an item (e.g. a module or a 
    //! struct). They use the comment syntax //! and must go at the top of the
    //! enclosing item. 
    struct Bar {
        pub baz: i64
        //! This is invalid. Inner comments must go at the top of the struct,
        //! and must not be placed after fields.
    }
}

외부 문서 주석

/// Outer documentation comments go *outside* the item that they refer to.
/// They use the syntax /// to distinguish them from inner comments.
pub enum Test {
    Success,
    Fail(Error)
}

협약

/// In documentation comments, you may use **Markdown**.
/// This includes `backticks` for code, *italics* and **bold**.
/// You can add headers in your documentation, like this:
/// # Notes
/// `Foo` is unsuitable for snafucating. Use `Bar` instead.
struct Foo {
    ...
}

/// It is considered good practice to have examples in your documentation
/// under an "Examples" header, like this:
/// # Examples
/// Code can be added in "fences" of 3 backticks.
///
/// ```
/// let bar = Bar::new();
/// ```
///
/// Examples also function as tests to ensure the examples actually compile.
/// The compiler will automatically generate a main() function and run the
/// example code as a test when cargo test is run.
struct Bar {
    ...
}

문서 테스트

문서 주석의 코드는 cargo test 의해 자동으로 실행됩니다. 이를 "문서 테스트"라고하며, 귀하의 사례가 효과가 있고 귀하의 나무 상자 사용자를 오도하지 않도록 도와줍니다.

크레이트 루트에서 친척을 가져올 수 있습니다 (예 : 숨겨진 extern crate mycrate; 가있는 경우)

/// ```
/// use mycrate::foo::Bar;
/// ```

문서 테스트에서 코드가 제대로 실행되지 않으면 다음과 같이 no_run 속성을 사용할 수 있습니다.

/// ```no_run
/// use mycrate::NetworkClient;
/// NetworkClient::login("foo", "bar");
/// ```

당신은 또한 당신의 코드는 다음과 같이 당황해야 함을 표시 할 수 있습니다 :

/// ```should_panic
/// unreachable!();
/// ```