Silent failure to document crate-level public functions

[scouten-adobe]

tl;dr: Functions exported at crate scope are silently ignored by docs.rs. This bug does not occur with current stable cargo docs build.

Detail

For reference, see the following from version 0.7.0 of c2pa crate:

pub use crate::openssl::signer::{get_signer, get_signer_from_files};

Note that crate::openssl and crate::openssl::signer are not public and that get_signer and get_signer_from_files are both functions that are verified to be accessible from outside the crate.

When I run cargo docs --open locally (using Rust stable 1.62.0 on MacOS), I see a top-level "Functions" entry and these two functions are described as I would expect.

However, the generated docs for this version of this crate on docs.rs do not contain a top-level "Functions" entry and searching on either of the function names yields a "No results" screen.

I would expect either that the docs.rs documentation would match what I can generate locally, or some sort of error would describe the reason why that could not happen.

We're contemplating redesigning away from this API pattern in part because of this bug. See contentauth/c2pa-rs#72

[Nemo157]

Those functions are gated behind a non-default feature. If you want that feature active for the docs built on docs.rs you can add a metadata section to your Cargo.toml, see the features or all-features keys in https://docs.rs/about/metadata.

Locally you're in a workspace where one of the other members enables the file_io feature, so you get the docs with that feature active.

[scouten-adobe]

@Nemo157 I eventually worked that out. The following things were not at all intuitive/obvious to me and took more than a little sleuthing to derive:

1. (As you've said) Non-default features are disabled by default.
2. docs.rs uses nightly builds of rustdoc, not stable.
3. Automatic annotations for feature availability are available in nightly but not stable builds of rustdoc: https://doc.rust-lang.org/rustdoc/unstable-features.html#doc_auto_cfg-automatically-generate-doccfg. (Which made me thankful for the previous item!)

For those who come across this issue later, the following PR in our project (contentauth/c2pa-rs#73) made several changes you might also want:

1. Reconfigured our PR validation to use an environment very similar to docs.rs so we can preflight doc changes.
2. Turned on the all-features flag as described by @Nemo157.
3. Enabled doc_auto_cfg so that feature-gated functions and modules are annotated automatically.

Hope this helps!