This document contains all information related to developer documentation for this repository's source code.
Let's say you want to learn what a Component
or an AttributeValue
is.
Where do you look?
You can generate and open the docs in your browser to find out!
buck2 run //lib/dal:doc -- --document-private-items --open
Our Rust crates contain module and documentation comments that can be generated into static webpages by rustdoc
.
When in doubt, see if doc
target for a Rust-based library has what you are looking for.
As previously mentioned, for our Rust crates, we leverage rustdoc
for seamless integration with
IntelliJ Rust, rust-analyzer, and more.
We try to follow the
official "How to write documentation" guide
from rustdoc
as closely as possible.
Older areas of the codebase may not follow the guide and conventions derived from it.
We encourage updating older documentation as whilst navigating through SI crates.
- RFC-1574:
more API documentation conventions for
rust-lang
- "Making Useful Documentation Comments" from "The Book": a section of "The Book" covering useful documentation in the context of crate publishing