Documentation no longer lists required features

[tim-weis]

Summary

Starting with version 0.52.0, the documentation published here no longer lists all/some required features.

For example:

• OutputDebugStringW doesn't list any features
• GetMessageW doesn't list the full set of features

It looks like the requirements for the containing module have dropped off.

Crate manifest

No response

Crate code

No response

[ChrisDenton]

Probably #2671. I think it no longer adds namespace features to the list of features.

EDIT: specifically

-            let mut tokens = format!(r#"`\"{}\"`"#, to_feature(self.namespace));
+            let mut tokens = String::new();

[kennykerr]

Yep the docs no longer explicitly include the feature for the enclosing module. This caused a huge amount of redundant doc comments and markup. A bit less intuitive for sure, but a tradeoff I think is worthwhile until I find a long-term replacement for rustdoc...

[junglie85]

OutputDebugStringW does not show up in search results to be able to find the module to use, it only shows the kernel32.dll.c definition. Maybe an edge case, but that makes it difficult to find which feature to enable.

[ChrisDenton]

From the docs, you just need to click on the parent module (Debug)

[junglie85]

That's fair - I tend to hunt around the GitHub repo rather than use the published docs.

[kennykerr]

Unfortunately, github's search capabilities are foiled by the size of the windows-rs repo.

[riverar]

Think we should revert this change, this is markedly worse UX for no apparent benefit.

[tim-weis]

The only reason I care about the required features is to copy them into the features table of a Cargo.toml file. This used to work well when all features were listed.

After the change, things are far less convenient. It's not entirely unworkable as long as only the containing module's feature is required. When more features are required the documentation starts to feel very hostile (just go through the number of steps needed to get GetMessageW's features into a Cargo.toml).

Someone who knows their way around this crate may merely be inconvenienced. To anyone new, this may be reason enough to look into alternatives.

Reverting this change would be very much appreciated.

[ChrisDenton]

I wonder if it would help to remove the explicit need for things like Foundation and Win32_Foundation and instead make them automatically implied by using the relevant namespaces? They're almost certainly needed and I think they should not add significantly to code size in any case.

[kennykerr]

Yes, I'm looking for ways to reduce the feature complexity as simply reverting this change doesn't really solve the problem. Continuing to use rustdoc in this way is just not sustainable.

[tim-weis]

I'm looking for ways to reduce the feature complexity

I'm not objecting to that. I'm uncomfortable with having the documentation reflect a potentially simpler future world before it exists. Until we're there, the documentation should reflect the current state, with feature complexity and all.

[kennykerr]

cargo doc has a new doc_auto_cfg feature that finally seems to figure this out based on cfg attributes so we don't have to generate the redundant doc comments any longer. rust-lang/rust#43781

Unfortunately, formatting is not that great.