rust-windowing / rust-windowing/winit
Event lifecycle docs (contribution volunteer)
Nobody has claimed this yet.
- Dominant language
- Rust
- Stars
- 6.2k
- Forks
- 1.3k
- Avg merge
- 2d 19h
- Merged PRs (30d)
- 9
Description
One thing I struggled with when starting with winit is a clear idea of the "lifecycle" of an event loop. That is: what's the order of events I can expect to be dispatched to the EventLoop::run closure? I would like to contribute some docs to this if you'd be amenable.
I think this problem is particularly important for winit because - as a new user - you're immediately made aware that winit is being very careful about cross-platform behaviour (being required to pass a move closure to run which entirely hijacks your main thread makes this clear), but one of the core aspects of that behaviour isn't immediately clear.
I realise most of this information is already in the docs - across the root docs, Event, and ControlFlow docs. I think all of those are appropriate docs for where they are, but propose an additional section in the root docs specifically to teach new users the high-level of what to expect from events. Ideally with a simple flowchart showing the most common orders of events (see, for example, this from the android docs).
I'd be happy to draft something, but wanted to check that it would be desirable first. Also, since I still don't fully understand this topic, it would require some careful review.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the existing root event-handling documentation alongside the Event and ControlFlow docs linked in the issue. Map the high-level event-loop lifecycle and common event orders across the documented platforms, then draft an additional root-docs section with a simple flowchart. Done means the lifecycle is explained clearly for new users and the content receives careful review.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100