Add docs feature

[kennykerr]

This avoids documentation generation when undesired.

Fixes: #2665

[tim-weis]

This took me a moment to comprehend, so I'm leaving a few notes here in case someone else gets confused in the future.

What

This PR gates documentation generation for the windows and windows-sys crates behind a feature named "docs". This feature is disabled by default. Other crates (notably windows-core) are unaffected by this change.

How To

The "docs" feature is intended to be used with cargo doc, exclusively (see feature selection in The Cargo Book). By default, no documentation is generated. To enable documentation generation, e.g., for the windows crate run the following command line:

cargo doc --features windows/docs

Similarly for the windows-sys crate.

How Not To

The "docs" feature is a regular Cargo feature that can be enabled from a Cargo.toml file. Clients of windows and windows-sys, and crate authors in particular, should refrain from doing so, as it would effectively invalidate the ability to generate documentation for windows and windows-sys on client request.

[kennykerr]

Thanks Tim, that's helpful.

[tim-weis]

Glad to have you back, Kenny!

[LikeLakers2]

@kennykerr Thanks! :)

@tim-weis Let me add a "why" to your notes.

In most crates, the documentation generated isn't very much - the disk space used is so minimal, and the additional files add very little time to a cargo clean. However, with windows and windows-sys, the opposite is true - they generate so much documentation as to use up quite a bit of disk space, and the amount of files generated cause cargo clean to take forever.

Thus, this feature flag serves to solve that issue, by hiding the documentation unless you ask for it, and thus cut down on the amount of files that the crates generate when you run cargo doc.

Hope that helps. :)

---

P.S. It appears that my comments at #2665 (the issue this fixes) have restarted the discussion of rust-lang/cargo#4049, a suggestion that allows skipping certain crates from cargo doc. See rust-lang/cargo#4049 (comment).

Maybe windows-sys and windows won't actually need a docs feature for that long?