하소연 겸 rust 문서 보는 팁

bevy snake 튜토리얼을 한번 쭉 훑어본 뒤 직접 따라해보고 있습니다. 필요한 걸 찾으려면 문서를 봐야 하는데, 아직 bevy 가 0.5 인 것도 있고 제가 rust 로 실제 코드를 거의 짜보지 않아서 문서 보는 방법을 잘 모르다보니 좀 버벅이네요. 이 과정에서 알게 된 몇 가지 자잘한 팁? 비스무리한 걸 짧게라도 생각난 김에 얘기해보고자 합니다.

(disclaimer: 저는 rust 초보입니다. 헌터 1:1 초보만)

docs.rs 에서 뭔가 검색결과에 없으면 cargo doc --open

bevy 는 workspace crate 로, 하위에 여러 crate 가 들어있는 저장소입니다. docs.rs 에서 API 나 객체를 검색하다가 왜인지 모르게 안 나오는 경우가 있었는데, 알고보니 문서를 이리저리 둘러보다가 하위 crate 의 문서로 이동해있는 상태였습니다. bevy_sprite 의 struct 를 검색했는데 현재 문서가 bevy_app 이면 나올리가 없죠.

뭐가 문제인지는 모르겠는데 docs.rs 에 [src] 버튼이 없는 경우도 있고 그러더라구요. 방금 해봤는데 cargo doc --open 에서는 [src] 버튼이 나옵니다.

이 struct 가 뭔지 궁금할 땐 trait impl 란을 보자

bevy_sprite::SpritePlugin 은 이름만 봐도 딱 Plugin 임을 알 수 있지만, 명확히 알려면 "Trait Implementation" 란을 보면 Plugin trait 을 구현한다고 나와있습니다. 당연한 거긴 한데...

...이게 Component (bevy 프레임워크의 개념) 를 구분하는 데에는 아쉽게도 도움이 되지 않더군요. 이 경우, blanket implementation (일종의 자동 구현) 에 있었습니다. 'static + Send + Sync 에 모조리 구현해놔서 사실상 도움이 안 되던. 원래 그런 컨셉이기도 하구요.

모듈 단위의 문서를 먼저 보자

두말하면 잔소리가 되겠습니다. 모듈 단위 문서는 개요를 설명하기 딱 좋은 곳이죠. struct 나 trait 같은 개별 구성 요소가 문서화가 덜 된 경우여도 모듈 단위에는 무슨 모듈인지에 대한 설명이 있는 경우가 있더라구요.

영 못 찾겠으면 소스로 직행 (...) 하거나 아니면 examples 를 보자

사용하는 crate의 구조가 타입만으로 알기 어려운 경우 등등 문서만으로는 곤란한 경우 코드를 바로 확인해보는 것도 좋은 방법 같습니다. 아 이건 문서 잘 보는 법이 아니네요,,, 좋게 생각하면 소스 자체가 문서인 게 제일 좋은 코드 아니겠습니까. rust 에코시스템은 sub-crate 로 쪼개는 걸 많이들 하는 거 같기도 해서 잘 구성해놨다면 찾기도 편하더군요,,,

bevy 0.5 의 경우 프로젝트 초기다보니 원하는 구성요소가 Component 인지 Resource 인지 잘 모르겠다인 경우가 많은데 trait Plugin 의 build() 구현 부분에 초기화가 있습니다. IDE로 찍어서 들어가보면 바로 이게 뭔지 파악이 가능하더군요.

그 외에도 많은 rust 프로젝트의 소스코드에 examples 폴더를 만들어두고 있습니다. 예시 폴더는 마치 쿡북처럼 사용할 수 있죠. 아마 cargo 가 예시 폴더를 지원해주는 게 아닐까 싶네요.