Document everything

[Lonami]

Hi! The vast majority of documentation for winapi seems to be available on GitHub under https://github.com/MicrosoftDocs/sdk-api.

Would it be possible to run some form of process to clone the repository, walk through all markdown files, and embed them as documentation in this repository? It would streamline the usage of the crate a lot.

I'm aware this would be a lot of work, and the repository doesn't seem to have any license so maybe one should ask first, but I thought I'd throw the idea in here.

[tim-weis]

This is probably something that could more easily be worked into the windows-rs crate, as that auto-generates Rust bindings. It is sourced from the win32metadata project. The latter produces ECMA-335 metadata from the Windows API surface. I suppose that documentation can be encoded by way of custom attributes, although I'm not aware that doing so has ever been formalized.

[Lonami]

Unfortunately, the documentation cannot easily be published using GitHub Pages because GitHub has a 100MB limit on files and rustdoc generates a few files that are well over that limit. The build also cannot be automated with GitHub Actions as it takes around 30 minutes (mostly single-threaded) and will exhaust the CI build's resources (rustdoc allocates around 20GB of memory) and ultimately fails the build. A major reason for this is that cargo doc generates a multi-gigabyte windows.rs.html file containing the pretty-formatted version of the generated windows.rs file and there does not appear to be a way to exclude source code browsing using the Rust document generator. (source)

Well damn, I didn't expect that to be so ridiculous. Feel free to close if you think this idea isn't happening.

---

But what about adding an auto-generated link to Microsoft's documentation? This should be a fairly simple mapping, and would still be useful.