I am building our project documentation using
cargo doc and have not been able to work out whether I should be using the
The documentation states:
Document optimized artifacts with the
My assumption is that this means it will only be documenting those modules and dependencies included in a
release build, but I'm not sure if that is correct.
I suppose I have two questions: Is my understanding of the flag correct, and if so, for overall project documentation would best practice be to document the
release version of the project or the
Normally it will not make a difference, but there are certain conditional compilation markers such as
#[cfg(debug_assertions)] that depend on whether you're in release mode or not (+ details on profiles).
I usually just run
cargo doc (without the
--release) because it's usually faster. The resulting documentation should be identical because the source code being compiled is the same, and that's what
rustdoc actually uses when generating documentation.
The only exception is if certain public functions are only compiled with
cfg attribute is used to exclude things when not compiling in debug mode.
I'd argue it's bad practice to change the public API based on whether you compile in debug or release mode though (that's what feature flags are for), and have never actually seen this happen in the wild.
For future reference, I normally have the following running on a terminal in the background:
$ cargo watch --clear \
-x "check --all-features" \
-x "test --all-features" \
-x "doc --document-private-items --all-features" \
-x "build --release --all-features"
The cargo-watch tool will re-run the provided commands every time it detects a file change. I run
check first because that's gives you quick feedback on the last change, then I run
test (in debug mode) to make sure my tests pass. Once the
test complete I'm happy and anything after that (e.g. updating the API docs and compiling in release mode) is just a nice to have.
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.