Documentation lags new release.

jacksonbrim commented 3 months ago

Summary

Documentation for the windows crate is on 0.54, yet latest release is 0.56.

https://microsoft.github.io/windows-docs-rs/doc/windows/index.html

It's impossible to tell if a trait has been modified from release to release or if it is hidden behind a feature flag.

The following is from the rss example. The Items() method is documented for SyndicationFeed in the documentation (0.54).

Using the feature search, the only feature I can manage to find for this Struct is "Web_Syndication".

https://microsoft.github.io/windows-rs/features/#/0.56.0

It would be nice to simply have the feature flags in the documentation page, instead of having to search separately on the features search page.

Crate manifest

[package]
name = "windows-examples"
version = "0.1.0"
edition = "2021"

[dependencies]
windows = { version = "0.56.0", features = [
"Web",
"Web_Syndication",
"Devices_Enumeration",
"Win32_Media_Audio",
"implement",
"Win32_Networking_BackgroundIntelligentTransferService",
"Win32_System_Com", 
"Win32_Foundation",
"Win32_System_Threading",
"Win32_UI_Accessibility", 
"Win32_UI_WindowsAndMessaging", 
"UI_UIAutomation", 
"Data_Xml_Dom",
"Foundation_Numerics",
"Win32_System_Com",
"Win32_Graphics_Direct2D_Common",
"Win32_Graphics_Direct3D",
"Win32_Graphics_Direct3D11",
"Win32_Graphics_Dxgi_Common",
"Win32_Graphics_Gdi",
"Win32_System_LibraryLoader",
"Win32_System_Performance",
"Win32_System_SystemInformation",
"Win32_UI_Animation",
"Win32_UI_WindowsAndMessaging",
] }
windows-core = "0.56.0"

Crate code

use windows::{
    core::*,
    Foundation::Uri,
    Web::Syndication::{SyndicationClient},
};

pub fn main() -> Result<()> {
    let uri = Uri::CreateUri(h!("https://blogs.windows.com/feed"))?;
    let client = SyndicationClient::new()?;

    client.SetRequestHeader(
        h!("User-Agent"),
        h!("Mozilla/5.0 (compatible; MSIE 10.0; Windows NT 6.2; WOW64; Trident/6.0)"),
    )?;

    let feed = client.RetrieveFeedAsync(&uri)?.get()?;

    for item in feed.Items()? { // no method named `Items` found for struct `SyndicationFeed` in the current scope
        println!("{}", item.Title()?.Text()?);
    }

    Ok(())
}

riverar commented 3 months ago

Hey @jacksonbrim,

I'll get the docs regenerated. We handle this manually because rustdoc needs ~20GB of memory to complete the operation and generates ~quarter million files that then need to get checked in.

Regarding features not in the rustdocs: this is intentional. See: https://github.com/microsoft/windows-rs/pull/2830. We'll take a note to improve the search, thanks!

jacksonbrim commented 3 months ago

Ah, I see. My next suggestion was going to be to use doc_auto_cfg to generate feature flags, but I see that debate has already been had.

riverar commented 3 months ago

New docs are live https://microsoft.github.io/windows-docs-rs/doc/windows/. Will close this issue as complete; we'll tackle improving the search next. Thanks!

ChrisDenton commented 3 months ago

Regarding features not in the rustdocs: this is intentional. See: https://github.com/microsoft/windows-rs/pull/2830. We'll take a note to improve the search, thanks!

I would note that rustc itself is getting better at suggesting features to enable. Though if something needs multiple features enabled, it unfortunately won't tell you so upfront. Example session:

> cargo build
   Compiling windows v0.56.0
   Compiling win v0.1.0 (R:\win)
error[E0433]: failed to resolve: could not find `Win32` in `windows`
  --> src/main.rs:2:15
   |
2  |     use windows::Win32::Storage::FileSystem::CreateFileW;
   |                  ^^^^^ could not find `Win32` in `windows`
   |
note: found an item that was configured out
  --> R:\rust-lang\Cargo\registry\src\index.crates.io-6f17d22bba15001f\windows-0.56.0\src\Windows/mod.rs:44:9
   |
44 | pub mod Win32;
   |         ^^^^^
   = note: the item is gated behind the `Win32` feature

For more information about this error, try `rustc --explain E0433`.
error: could not compile `win` (bin "win") due to 1 previous error

> cargo add windows -F 'Win32'
    Updating crates.io index
      Adding windows v0.56.0 to dependencies
             Features:
             + Win32
             + Win32_Foundation
             687 deactivated features

> cargo build
   Compiling windows v0.56.0
   Compiling win v0.1.0 (R:\win)
error[E0433]: failed to resolve: could not find `Storage` in `Win32`
  --> src/main.rs:2:22
   |
2  |     use windows::Win32::Storage::FileSystem::CreateFileW;
   |                         ^^^^^^^ could not find `Storage` in `Win32`
   |
note: found an item that was configured out
  --> R:\rust-lang\Cargo\registry\src\index.crates.io-6f17d22bba15001f\windows-0.56.0\src\Windows\Win32\mod.rs:26:9
   |
26 | pub mod Storage;
   |         ^^^^^^^
   = note: the item is gated behind the `Win32_Storage` feature

For more information about this error, try `rustc --explain E0433`.
error: could not compile `win` (bin "win") due to 1 previous error

> cargo add windows -F Win32_Storage
    Updating crates.io index
      Adding windows v0.56.0 to dependencies
             Features:
             + Win32
             + Win32_Foundation
             + Win32_Storage
             686 deactivated features

> cargo build
   Compiling windows v0.56.0
   Compiling win v0.1.0 (R:\win)
error[E0432]: unresolved import `windows::Win32::Storage::FileSystem`
  --> src/main.rs:2:31
   |
2  |     use windows::Win32::Storage::FileSystem::CreateFileW;
   |                                  ^^^^^^^^^^ could not find `FileSystem` in `Storage`
   |
note: found an item that was configured out
  --> R:\rust-lang\Cargo\registry\src\index.crates.io-6f17d22bba15001f\windows-0.56.0\src\Windows\Win32\Storage\mod.rs:18:9
   |
18 | pub mod FileSystem;
   |         ^^^^^^^^^^
   = note: the item is gated behind the `Win32_Storage_FileSystem` feature

For more information about this error, try `rustc --explain E0432`.
error: could not compile `win` (bin "win") due to 1 previous error

> cargo add windows -F Win32_Storage_FileSystem
    Updating crates.io index
      Adding windows v0.56.0 to dependencies
             Features:
             + Win32
             + Win32_Foundation
             + Win32_Storage
             + Win32_Storage_FileSystem
             685 deactivated features

> cargo +nightly build
   Compiling windows v0.56.0
   Compiling win v0.1.0 (R:\win)
error[E0432]: unresolved import `windows::Win32::Storage::FileSystem::CreateFileW`
   --> src/main.rs:2:6
    |
2   |     use windows::Win32::Storage::FileSystem::CreateFileW;
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ no `CreateFileW` in `Win32::Storage::FileSystem`
    |
note: found an item that was configured out
   --> R:\rust-lang\Cargo\registry\src\index.crates.io-6f17d22bba15001f\windows-0.56.0\src\Windows\Win32\Storage\FileSystem\mod.rs:434:15
    |
434 | pub unsafe fn CreateFileW<P0, P1>(lpfilename: P0, dwdesiredaccess: u32, dwsharemode: FILE_SHARE_MODE, lpsecuri...
    |               ^^^^^^^^^^^
    = note: the item is gated behind the `Win32_Security` feature

For more information about this error, try `rustc --explain E0432`.

> cargo add windows -F Win32_Security
    Updating crates.io index
      Adding windows v0.56.0 to dependencies
             Features:
             + Win32
             + Win32_Foundation
             + Win32_Security
             + Win32_Storage
             + Win32_Storage_FileSystem
             684 deactivated features

> cargo build
   Compiling windows v0.56.0
   Compiling win v0.1.0 (R:\win)
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 3.02s

Note that the only two features actually needed here are Win32_Security and Win32_Storage_FileSystem because the others are implicit. However, rustc doesn't know that. It would be good if we can make cargo fix just work for this,

microsoft / windows-rs