Using --release for cargo doc

help
1

I am building our project documentation using cargo doc and have not been able to work out whether I should be using the --release flag.
The documentation states:

Document optimized artifacts with the release profile.

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 dev?

Thanks!

2

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).

1 Like
3

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(debug_assertions)]. This 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 check and 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.

2 Likes
4

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.