Hide `windows-sys`'s documentation behind a feature flag?

[LikeLakers2]

Suggestion

Hi! I've been building a program that uses the bevy game engine crate, and in the midst of this, I've found it useful to render documentation for everything via cargo doc.

However, I noticed that the windows-sys crate generates quite a lot of documentation. Unfortunately, cargo doc has no way to exclude certain dependencies without excluding all dependencies (the --exclude flag only seems to work on packages that are within the current workspace).

I don't believe this is an issue with the windows-sys crate, per se - it's doing its job just fine. However, unless a user is using windows-sys directly, they may not need to see windows-sys's documentation anyways - meaning windows-sys's documentation is simply wasting disk space, and worse, making cargo clean take a lot longer due to the mass amount of files generated.

Still, some users may need windows-sys's docs, so hiding them behind a blanket #[doc(hidden)] may not be a good idea. Perhaps windows-sys could attach #[doc(hidden)] to most stuff, unless a certain feature flag (let's say windows-sys/render_docs) is specified?

I just think it may be useful to avoid generating so much documentation unless a user needs it.

[riverar]

So you'd like to generate docs for your crate and all dependencies except windows-sys, right? (Just making sure I understand, thanks!)

[LikeLakers2]

Yes. windows-sys generates a lot of documentation, and because I'm using the bevy game engine crate, it abstracts away much of the stuff needed to make a program - so I have no need to look at the windows-sys documentation ever. So I'd like a way to avoid generating windows-sys documentation.

There is rust-lang/cargo#4049, however that was opened in 2017 with no plans to add it yet. Thus, as a stopgap, I'm hoping windows-sys can provide a method to skip generating so much documentation.

[kennykerr]

Hey, sorry for the delay. Been off the grid camping. 🏕️

Just catching up here but this is what I do. Is that sufficient?

cargo doc -p package --all-features --no-deps

[LikeLakers2]

@kennykerr While it could work, there's some problems I'd have with using that approach.

When I'm building apps with bevy, there's often a large number of crates named bevy_* that I'm interested in. Combine this with other dependencies that I've added to the app, and now I have a rather large number of -p parameters to specify just to exclude windows-sys from being documented.

Additionally, I use cargo-watch in order to automatically regenerate documentation as I write my app. Currently, I have cargo watch --exec doc as a VSCode task that I (manually) run whenever I open a project - and then documentation generation is taken care of for me for as long as VSCode is open. However, having to specify all the packages I'd want would result in me needing to write one cargo-watch command per project, not to mention having to keep it up-to-date when dependencies change.

So suffice to say, I'm not exactly keen on that approach.

[kennykerr]

Fair enough. I've been meaning to reduce the overhead of doc comments for other reasons, so I'll keep this in mind for that effort.

[kennykerr]

Mainly just for me: if we add #![doc(hidden)] to the crate's lib.rs file then all docs are effectively removed, rather than having to add the attribute to each and every item individually.