Clarify first section of module docs

[kwest-ng]

A reddit user posted a question to r/rust, which expressed a confusion in how to get an ActiveEventLoop, so that they could use ActiveEventLoop::create_window(), when the docs only showed how to create an EventLoop.

I read through and replied to help them understand the relationship between EventLoop, Window, ActiveEventLoop, and ApplicationHandler, but I felt that the first-seen docs at the top of the user-facing winit module were a bit confusing. Specifically, talking about how to create a Window with seemingly no example of how to do so (the example later in the Event Handling section seemed disconnected), and linking to ActiveEventLoop::create_window() after only talking about EventLoop felt odd and confusing, which is what the original user seemed to struggle with.

I reordered a few docs and added a 2-paragraph rundown of the core API Architecture, which I believe would have prevented both my initial confusion, and the confusion of the original poster on reddit.

Full disclosure, I have never actually seen winit code or its API docs before, I just benefit from it indirectly when it's used to create tools which I do use. I felt I could help with the docs so I gave a shot. Feel free to make suggestions or edits, or to simply close the PR if this is not wanted. I'm happy to follow this through if changes need to be made.

• Tested on all platforms changed
• Added an entry to the changelog module if knowledge of this change could be valuable to users
• Updated documentation to reflect any user-facing changes, including notes of platform-specific behavior
• Created or updated an example program if it would help users understand this functionality

[kchibisov]

I think the issue is mostly with the fact that it's not clearly documented what ActiveEventLoop is and how you get it. I'd probably add the docs explaining that it's a type state pretty much, and that.

[kwest-ng]

I'm not sure I understand what you'd be looking for, or how ActiveEventLoop is a "type state" (IIRC, this is a type-system-level pattern which does not apply here at all). Or, perhaps more clearly, I don't know what you're looking for that I haven't already done.

I think the issue is mostly with the fact that it's not clearly documented what ActiveEventLoop is and how you get it

I'd like to point out that I did explain what I think ActiveEventLoop is, which is a connection between 1 or more Windows and a single EventLoop. I also explained how you get it, by implementing ApplicationHandler.

If my explanations were wrong and unusable, then I'm just likely not the person to make this docs change (I did say I never used winit directly). Otherwise, I'm still happy to make changes and see this through.