No documentation on docs.rs for multicast_all_v4 and set_multicast_all_v4

[proski]

Functions multicast_all_v4 and set_multicast_all_v4 are missing from the Socket documentation: https://docs.rs/socket2/0.5.8/socket2/struct.Socket.html

Those functions are documented in the source code for version 0.5.8 (commit 60d118f) but that documentation is missing from the docs.rs site.

I don't know why the documentation is missing. For comparison, the documentation for set_reuse_port is on the site.

[Thomasdezeeuw]

Might be something wrong with the cfg attribute:

socket2/src/socket.rs

Line 1418 in 0ae0c3a

#[cfg_attr(docsrs, doc(cfg(all(feature = "all", target_os = "linux"))))]

[proski]

It looks like all functions that depend on the all feature are undocumented.
I suspect that docs.rs fails to build the documentation using the package.metadata.docs.rs section in Cargo.toml and falls back to the default build without using that section. As a result, --all-features is not passed to the build.
Most likely, passing --cfg docsrs conflicts with the docs.rs invocation that passes docsrs already: https://docs.rs/about/builds
It's also possible that one of the targets is unavailable.

Another issue with the documentation is the lack of annotations that some functions are only available for specific platforms. I would consider adding a new (crate) feature that would enable the doc_auto_cfg (unstable Rust) feature and make the docsrs use unnecessary - it's a lot of duplicate code. And having a feature would make it easier to test the documentation generation locally.

[Darksonn]

Most likely, passing --cfg docsrs conflicts with the docs.rs invocation that passes docsrs already

We pass that in Tokio in the same way, and it works fine there, so that can't be the problem.

[proski]

There are actually docs.rs logs available.
https://docs.rs/crate/socket2/0.5.8/builds

Indeed, --cfg docsrs is passed twice on the same command line. However, it doesn't trigger any warnings.

--all-features is passed to cargo, there are no warnings about it.

There is a warnings about the target for all targets (even for x86_64-unknown-linux-gnu), so it's probably not a real issue we should be worrying about.

[INFO] [stderr] warning: target filter specified, but no targets matched; this is a no-op

But the logs made me realize that there are separate sets of documentation for every platform, and I was looking at the documentation for the default target, aarch64-apple-ios.

I can switch "Platform" on the toolbar on top of the site to x86_64-unknown-linux-gnu and I get the expected documentation. multicast_all_v4 is documented, there is even a notice that it requires the all feature and Linux. https://docs.rs/socket2/0.5.8/x86_64-unknown-linux-gnu/socket2/struct.Socket.html#method.multicast_all_v4

Oh well, it must be a "user issue". Learning something every day.

But let's consider what could have been done better. Perhaps x86_64-unknown-linux-gnu should be the default target, and it's more feature rich.

I also assumed that something was wrong in the cfg_attr directives. I believe they are unnecessary if feature(doc_auto_cfg) is used.

I wish rustdoc would produce a single set of documentation (I assumed that was the case), but it must be a major task and it cannot be fixed in socket2.

Please feel free to close this issue after reading this.

[proski]

Now I now that the documentation is platform specific. #554 will make x86_64-unknown-linux-gnu the default once a new release is made. Closing this issue as "user error".