Bundle, and / or link to, microsoft documentation

[mpowell90]

Suggestion

Hey folks,

As a new-comer to the microsoft rust development experience i've found the generated rust docs are lacking in detail compared to the official microsoft docs.

I can understand the microsoft docs will always be the primary source of truth but bundling any subset of the following suggestions would greatly improve the rust development experience both through docs.rs and in the IDE.

As i've linked to NOTIFYICONDATAW above, i'll provide screenshots of that resource below for additional context.

Suggested inclusions:

• struct description, e.g:

• member type descriptions, e.g:

• constant descriptions, e.g:

• remarks sections, e.g:

Alternative

As a bare minimum provide links in the generated rust docs to the relevant microsoft docs pages would reduce some friction. These links could just be on the structs descriptions rather than at every level (members, constants, etc...)

[kennykerr]

We've looked into this in the past but there's no practical way to incorporate the docs mainly because there are no permalinks we can depend on and replicating the docs would completely overwhelm rustdoc.

[mpowell90]

Hi Kenny Kerr (@kennykerr), thanks for the response.

It's honestly surprising that given all the documentation that is available from microsoft online, including github repos like https://github.com/MicrosoftDocs, that this content isn't exposed somewhere in md files or equivalent. Would be awesome to see something like this be championed internally as no doubt the whole ecosystem would benefit. I read somewhere that the win32 docs were once upon a time available for offline download but was stopped being offered.

I know the the objc2 maintainers are looking at something similar for the apple docs but they can parse apple documentation from a build machine madsmtm/objc2#808.

I'm also surprised by your comment about overwhelming rustdoc, some pretty big libraries utilise it and it seems to function fine.

As you pointed out without permalinks you cannot fully rely on links but naive solution would be a hashmap of symbol -> microsoft docs web link, then scrape the web pages for the relevant string comments at build time. If a link fails because it no longer exists then at least the CI could catch it and fail the build. I know its far from ideal and another maintainence burden, but its a step in the right direction.

If you are amenable to the scrapping idea then i'd be interested in exploring further and producing a PR.
Or open to other suggestions to push things forward?

[tim-weis]

I'm also surprised by your comment about overwhelming rustdoc, some pretty big libraries utilise it and it seems to function fine.

That is the unfortunate reality. docs.rs isn't currently able to compile and/or host the documentation for the windows crate (even with all doc-comments stripped). This has been brought up several times in the past, e.g.,

• Documentation for specific version (latest version is 0.59.0, published documentation is for version 0.58.0) #3442
• [Feature Request] Full documentation builds on Docs.rs #309
• No reference documentation for windows 0.62 #3846

The Windows API documentation for Rust is the stop-gap solution for documentation generation that's hosted here.

Everyone (including myself) would love more complete documentation, but this issue is (and has been for years) blocked by the capabilities of docs.rs. Any forward progress would have to remove the roadblock in docs.rs first.

[kennykerr]

We're also moving away from the large crates - windows-sys and windows - that also push the limits of the Rust toolchain in many ways, and instead focus on dedicated, highly-optimized, library experiences. You can get a sense for that in this repo's readme.

[mpowell90]

wow ok, I stand corrected!

I didn't realise the extent of the issue and the depth of attempts that has been made to make this work to date.

Thanks for the additional info and links - its a great help!