Created attachment 256704 [details] [review]
ClutterEvent: Mention _get_source_device() in docs

It's too easy getting bitten by the ->device red herring, thinking
that it's the original input device the event originated from.

Review of attachment 256704 [details] [review]:

I agree, it should be clearer; thanks for the patch.

the same should probably be done for all ClutterEvent structures, not just for StageState and Key events.

to be fair, the entirety of ClutterEvent should be sealed, and you should use the accessor functions.

(In reply to comment #2)
> Review of attachment 256704 [details] [review]:
> 
> I agree, it should be clearer; thanks for the patch.
> 
> the same should probably be done for all ClutterEvent structures, not just for
> StageState and Key events.

StageStage? I'm guessing you mean Button. Those are the only ones where the field wasn't marked as "for future expansion". I know it's used in ClutterKeyEvent, which is why I changed the docs there.

> to be fair, the entirety of ClutterEvent should be sealed, and you should use
> the accessor functions.

I need to mention it in clutter_event_get_device() too.

(In reply to comment #3)
> (In reply to comment #2)
> > Review of attachment 256704 [details] [review] [details]:
> > 
> > I agree, it should be clearer; thanks for the patch.
> > 
> > the same should probably be done for all ClutterEvent structures, not just for
> > StageState and Key events.
> 
> StageStage? I'm guessing you mean Button.

ugh, Splinter highlighted the wrong structure.

> Those are the only ones where the
> field wasn't marked as "for future expansion". I know it's used in
> ClutterKeyEvent, which is why I changed the docs there.

ClutterCrossingEvent, ClutterMotionEvent, ClutterScrollEvent, and ClutterTouchEvent have a `device` field. they should all mention clutter_event_get_source_device().

> > to be fair, the entirety of ClutterEvent should be sealed, and you should use
> > the accessor functions.
> 
> I need to mention it in clutter_event_get_device() too.

yeah, that would be good.

Created attachment 256729 [details] [review]
ClutterEvent: Mention _get_source_device() in docs

It's too easy getting bitten by the ->device red herring, thinking
that it's the original input device the event originated from.

Review of attachment 256729 [details] [review]:

looks good.

Attachment 256729 [details] pushed as 676a7cd - ClutterEvent: Mention _get_source_device() in docs