windows-core crate should enable implement feature when building for docs.rs

[MarijnS95]

Suggestion

I tried very hard to link someone the #[implement] docs (there are none to begin with it seems: https://docs.rs/windows-implement/latest/windows_implement/attr.implement.html) via windows-core after deducing from crates/samples/windows/bits/src/main.rs that that is where this macro must reside / be reexported from... But couldn't find it.

As it turns out the docs.rs metadata doesn't turn on this feature (same for the windows::core docs generated at https://microsoft.github.io/windows-docs-rs/doc/windows/core/), can this be added so that the documentation is more complete? It could possibly use doc_cfg, and doc_auto_cfg or a manual #[doc(cfg(feature = "implement"))] to make it clear that this is not provided by default.

---

Perhaps there are more features that are currently undocumented on docs.rs? I haven't checked.

[kennykerr]

It's not really the windows-core crate. The windows crate documentation lacks this because it builds with no-deps.

https://github.com/microsoft/windows-docs-rs

Rust docs are generally miserable for large crates. Something I still need to deal with more fully.

[MarijnS95]

--no-deps is mostly a local thing to not build documentation for dependencies in place, but it can (and should!) still link to "external" documentation.

For the windows-core (title of this issue) crate specifically, https://crates.io/crates/windows-core says that the official docs are at https://docs.rs/windows-core/latest/windows_core/, those could have been built with the feature and link to https://docs.rs/windows-implement. Both crates are small.

For https://github.com/microsoft/windows-docs-rs you can specify multiple crates, e.g. -p windows -p windows-core -p windows-implement should get everything, together with --all-features`?

[MarijnS95]

Note that I'm mostly filing this issue on request, otherwise I would have created a PR immediately that adds:

[package.metadata.docs.rs]
features = ["implement"]
rustdoc-args = ["--cfg", "docsrs"] # Optional, in case we do the below

To core's Cargo.toml. And then see if the following works in its' lib.rs:

#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]

[kennykerr]

Not to worry. It's a little deeper than that as the macros are re-exported through the windows crate and those are hidden. I'll get it fixed up asap.

[MarijnS95]

Right, looking at it now the implement feature on windows-core is only for impl IUnknown/IInspectable_Vtbl, so it's more of a windows issue than windows-core :)

Thanks for looking into it!

[kennykerr]

#2696 adds the following:

[MarijnS95]

@kennykerr Ah so it does turn out that it's only an export from the windows crate, but in a local core module which reexports windows-core contents in addition to the implement and interface macros... that's confusing 🤔

Anyway, should the docs clarify that that these items are only available when the non-default features are enabled via feature(doc_cfg)? You don't have to use the full feature(doc_auto_cfg) but can instead use a local #[doc(cfg(feature = "implement"))] 👍

(Use something like #![cfg_attr(docsrs, feature(doc_cfg))] to only enable this for nightly builds, where one can pass RUSTDOCFLAGS=--cfg=docsrs)