Rust: 코드 문서화

안녕.
모든 프로젝트와 마찬가지로. 문서를 작성하는 것이 중요합니다. 이것은 우리가 알고 있듯이 코드를 생성할 때 매우 중요합니다. 휴식 후 프로젝트로 돌아오거나 새로운 사람이 작업을 맡을 때. 문서는 코드의 기능을 기억하거나 배우는 데 도움이 됩니다. 특정 결정 뒤에 있었던 생각.

여기에서 내가 배운 것의 몇 가지 예를 문서화할 것입니다. 이것은 광범위한 보기가 아닙니다.

자원

새로운 모든 것과 마찬가지로. 나는 약간의 연구로 시작했다. 나는 이것이 정말 좋다는 것을 알았다article . 기사를 꼭 보시길 권합니다.
규격도 있습니다docs

나는 내가 만든 dns 모듈에 대해서만 관심을 가질 것입니다.

먼저 이미 가지고 있는 문서를 생성해 보겠습니다.

cargo doc && cargo doc --open

그런 다음 dns 모듈로 이동한 다음 spf 로 이동합니다.

내부 함수 및 모듈 제외 기본

위 이미지에서 함수 목록을 볼 수 있습니다. 이러한 기능은 내부 구현 세부 정보입니다. 그리고 모듈 사용자는 이러한 사항을 알 필요가 없습니다. Rust의 문서화 시스템에서 이러한 기능을 숨기도록 합시다.

이를 위해 #[doc(hidden)] 명령을 사용합니다.

각 함수에 대해 함수 선언 바로 위에 이 명령을 추가해야 합니다. 이것은 src/dns/spf/mod.rs 내에서 수행됩니다.

#[doc(hidden)]
// Check if the initial character in the string `record` matches `c`
// If they do no match then return the initial character
// if c matches first character of record, we can `+`, a blank modiifer equates to `+`
fn return_and_remove_qualifier(record: &str, c: char) -> (char, &str) {

#[doc(hidden)]
fn remove_qualifier(record: &str) -> &str {

#[doc(hidden)]
fn capture_matches(
    pattern: Regex,

변경 사항을 보려면 문서를 재생성해야 합니다.

cargo doc

그런 다음 설명서 페이지를 다시 로드할 수 있습니다.

이제 내부 기능이 제거된 깔끔한 페이지가 생겼습니다.

#[doc(hidden)]를 사용하여 문서에서 테스트 모듈을 숨길 수도 있습니다.

#[doc(hidden)]
mod spf_a_mechanism_test;
#[doc(hidden)]
mod spf_mx_mechanism_test;
#[doc(hidden)]
mod spf_test;

모듈 수준 문서 추가

새 페이지를 자세히 보면. 이 모듈이 수행하는 작업에 대한 정보가 없음을 알 수 있습니다. 일부 모듈 수준 문서를 추가해야 합니다.
mod.rs의 맨 위에 추가하겠습니다.

//! This module creates an object that contains a deconstructed SPF DNS record.

그런 다음 문서를 다시 재생성합니다. (여기서부터는 생략)

함수 및 방법 문서화

Spf struct와 관련된 일부 기능을 문서화하는 것으로 이동하겠습니다.
Spf::new() 방법 문서화.


여기서 주목해야 할 중요한 점은 cargo test 를 실행할 때 백틱 사이의 코드가 실제로 테스트된다는 것입니다.

참고: 위의 예는 실제로 작동하지 않습니다. 실제 예제 체크 아웃을 찾고 있다면 다음 기사

Rust: 바이너리에서 라이브러리로 이동하고 테스트된 문서 예제를 추가합니다.

Adam.S ・ 5월 11일 ・ 5분 읽기

#rust #crate #test #documentation

parse() 방법 문서화.

/// Parse the contents of `source` and populate the internal structure of `Spf`
pub fn parse(&mut self) {

이것은 이제 우리에게 줍니다.

문서 내 링크

이 항목stack overflow link을 스타터로 참조하겠습니다.

다음은 작은 예입니다.

#[derive(Debug, Clone)]
pub enum MechanismKind {
    /// Represents a Mechanism of type include:
    Include,
    /// Represents a Mechanism of type redirect=
    Redirect,
}

impl MechanismKind {
    /// Returns `true` if the mechanism is [`Include`](MechanismKind::Include).
    pub fn is_include(&self) -> bool {
        matches!(self, Self::Include)
    }
    /// Returns `true` if the mechanism is [`Redirect`](MechanismKind::Redirect).
    pub fn is_redirect(&self) -> bool {
        matches!(self, Self::Redirect)
    }
}

우리가 사용하는 마크다운[label](link)과 마찬가지로 차이점은 실제 녹 코드MechanismKind::Include에서 사용하는 것처럼 링크가 작성된다는 것입니다.

메커니즘이 Include인 경우 Returns 'true'에 대한 Include를 클릭하면 Variants 아래의 Include 정의까지 연결됩니다.

오늘은 여기까지입니다. 새로운 흥미로운 것을 발견하면 이 기사를 업데이트하겠습니다.
도움이 되었기를 바랍니다.