문서, docs.rs & 게시

toolchain 의 마지막 조각은 생태계 자체야 — 크레이트를 찾고, 문서화하고, 게시하는 법. cargo doc, docs.rs, crates.io 가 고리를 닫아.

cargo doc: 코드에서 문서

cargo doc --open 이 네 /// 주석이랑 타입 시그니처에서 HTML 문서를 생성하고 브라우저에서 열어. 모든 Rust 크레이트 문서가 이렇게 생성돼서, 다 똑같이 보이고 탐색돼. 네 doc 주석 — 예제가 doctest 되는 그것 — 이 공짜로 다듬어진 레퍼런스 사이트가 돼.

docs.rs: 보편 문서 호스트

crates.io 에 게시된 모든 크레이트가 문서를 자동 빌드해서 docs.rs 에 호스팅돼. 크레이트에 의존하면 docs.rs/<crate> 가 네 레퍼런스야 — 그 정확한 버전 소스에서 생성된. 낯선 Rust 크레이트 탐색이 빠른 이유야: 문서가 항상 거기, 항상 최신, 항상 같은 포맷.

docs.rs 가 어떤 크레이트든 첫 정거장이야. 크레이트 API 를 추측하거나 웹 검색하기 전에 docs.rs/<crate-name> 을 열어. 소스에서 생성되고, 버저닝되고, 완전해 — 블로그 글이나 옛 버전에 대한 AI 기억보다 훨씬 믿을 만해. docs.rs 읽기가 핵심 Rust 기술이야.

게시와 semver

cargo publish 가 크레이트를 세상이 쓰게 crates.io 에 올려. 그 힘엔 semver 계약이 따라와: MINOR 나 PATCH 범프는 하위호환 유지; 깨는 변경은 MAJOR 범프 필요. 생태계 전체의 신뢰성이 크레이트 저자가 이걸 존중하는 데 — 그리고 Cargo 의 버전 해결이 그들이 그런다고 가정하는 데 — 달렸어. 이제 풀 고리를 봤어: 쓰고, 테스트하고, 문서화하고, 게시.

Code

로컬에서 문서 생성; 아무 크레이트나 docs.rs 에서 읽기·bash

# 네 크레이트 문서를 로컬에서 생성하고 열기
cargo doc --open

# 아무 의존성 문서든 자동 호스팅, 예:
#   https://docs.rs/serde     https://docs.rs/tokio

# 네 크레이트를 crates.io 에 게시 (semver 적용):
#   cargo publish    # MAJOR.MINOR.PATCH — 깨는 변경은 MAJOR 범프

Exercise

문서화된 함수가 있는 프로젝트에 cargo doc --open 을 돌리고 생성된 사이트를 둘러봐. 그다음 docs.rs/serde (또는 써본 아무 크레이트) 를 열어 특정 메서드의 시그니처랑 예제를 찾아. docs.rs 읽기가 왜 AI 한테 묻거나 몇 년 된 블로그 글 읽는 것보다 믿을 만해?

Hint

docs.rs 는 특정 버전의 정확한 소스에서 생성돼 — 오래되거나 환각일 수 없어. 블로그 글이나 AI 훈련 데이터는 바뀐 옛 API 를 묘사할 수 있어. Rust 크레이트엔 생성된 문서가 ground truth 야.

문서, docs.rs & 게시

cargo doc: 코드에서 문서

docs.rs: 보편 문서 호스트

게시와 semver

Code

External links

Exercise

Progress

댓글 0