How to read crates docs? (find path to the module)

[amarao]

It may be silly, but as I learn Rust, the biggest problem for me is to read docs for modules. One of the issues, that I can't construct proper use path to the object to use it.

Without concrete example it sounds silly, so here it is:

I have a piece of code which uses piston library. The have events iterator which return event, which, according to docs, is a simple enum: piston::event::Event - Rust

I have an event loop, and when I do debug print for events, I see exactly what was promised in docs: Render, PostRender, Idle, etc.

But when I try to do pattern matching on those, I just can't spell the path to things I want to match:
Docs says: piston::event::Event
I tried:

use piston;
...
match e {
   piston::event::Event => {println!("here");}
}

and got "could not find event in piston".
I've tried to write

use piston::event

but got the same error.
I've tried to break code to see what type it expects:

77 |                 1 => {println!("here");},
   |                 ^ expected enum `piston_window::Event`, found integer

I've tried to use this thing, but error is confusing:

77 |                 piston_window::Event::Render => {println!("here");},
   |                                       ^^^^^^ variant or associated item not found in `piston_window::Event`

Docs for piston_window are different: piston_window::Event - Rust

and it's not the things I see in debug output:

            match e {
                _ => {println!("{:?}", e);}
            }

Example of output is:

Update(UpdateArgs { dt: 0.008333333333333333 })
Idle(IdleArgs { dt: 0.00094002 })
Render(RenderArgs { ext_dt: 0.001123099, window_size: [800.0, 600.0], draw_size: [800, 600] })
AfterRender(AfterRenderArgs)
Idle(IdleArgs { dt: 0.005773664 })

As you can see, it's not the piston_window::Event, it looks like piston::event::Event, but I can't use it.

I'm completely lost. Either I don't know how to interpret docs, or something strange is there...

[17cupsofcoffee]

When matching on an enum, your patterns need to have the same structure as the thing you're matching on. For example, look at the docs for Event::Render:

Your pattern needs to look the same:

match e {
    Event::Render(render_args) => {
        // you can do something with the `render_args`here
    }
}

Here's some other examples:

enum Example {
    UnitVariant,
    TupleVariant(i32),
    StructVariant { field_name: i32 },
}

match e {
    Example::UnitVariant => { ... },
    Example::TupleVariant(i) => { ... },
    Example::StructVariant { field_name } => { ... },
}

I would recommend reading chapter 6 and chapter 18 of the book if you've not done so already, they go into further detail on this.

[bjorn3]

@amarao

I have a piece of code which uses piston library. The have events iterator which return event, which, according to docs, is a simple enum: http://docs.piston.rs/mush/piston/event/enum.Event.html

The docs on docs.piston.rs are very old. (Probably two of more years) Try piston - Rust instead. You can prefix the name of any crate on crates.io with docs.rs/ to get the documentation.

[17cupsofcoffee]

@bjorn3

The docs on docs.piston.rs are very old. (Probably two of more years) Try piston - Rust instead. You can prefix the name of any crate on crates.io with docs.rs/ to get the documentation.

Ah, yeah, Event is in the root of the crate in the current version: piston::Event - Rust

So the path would be piston::Event.

Also, the debug output is confusing in this case, because it's logging out the nested data within the Event, rather than the Event itself:

impl fmt::Debug for Event {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        match *self {
            Event::Input(ref input, _) => write!(f, "{:?}", input),
            Event::Loop(ref l) => write!(f, "{:?}", l),
            Event::Custom(ref id, _, _) => write!(f, "Custom({:?}, _)", id),
        }
    }
}

So you're seeing Loop events in your output, even though the thing you're printing is an Event, which is massively confusing.

I have no idea why someone would choose to do this rather than just deriving Debug

[amarao]

Thank you everyone for help!

This code does what I want (at a minimum level):

match e{
    piston::Event::Input(ref input, ts) => {
        println!("Input ts:{:?} input:{:?}", ts, &input);
    },
    _ => {},
}

Few key insights:

1. There is a huge difference between docs.piston.rs and https://docs.rs/piston (very much unexpected for me). Path in a module is straightforward, but one need to look for the version.
2. Events was heavily redone inside Piston whilst keeping debug output intact.

(And I've just learned to use ref inside match because Input does not support Copy trait).