Update and improve Window Documentation

[Selene-Amanita]

Objective

Improve the documentation relating to windows, and update the parts that have not been updated since version 0.8.

Version 0.9 introduced Window as a component, before that WindowDescriptor (which would become Window later) was used to store information about how a window will be created. Since version 0.9, from my understanding, this information will also be synchronised with the current state of the window, and can be used to modify this state.

However, some of the documentation has not been updated to reflect that, here is an example: https://docs.rs/bevy/0.8.0/bevy/window/enum.WindowMode.html / https://docs.rs/bevy/latest/bevy/window/enum.WindowMode.html (notice that the verb "Creates" is still there).

This PR aims at improving the documentation relating to windows.

Solution

• Change "will" for "should" when relevant, "should" implies that the information should in both direction (from the window state to the Window component and vice-versa) and can be used to get and set, will implies it is only used to set a state.
• Remove references to "creation" or be more clear about it.
• Reference back the Window component for most of its sub-structs.
• Clarify what needs to be clarified
• A lot of other minor changes, including fixing the link to W3schools in bevy_winit

Warning

Please note that my knowledge about how winit and bevy_winit work is limited and some of the informations I added in the doc may be inaccurate. A person who knows better how it works should review some of my claims, in particular:

• How fullscreen works: Update and improve Window Documentation #8858 (comment)
• How WindowResolution / sizes work: Update and improve Window Documentation #8858 (comment)
• What happens when WindowPosition is set to Centered or Automatic. From my understanding of the code, it should always be set back to At, but is it really the case? For example when creating the window, or when a WindowEvent::Moved is triggered or when Centered/Automatic by the code after the window is created, am I missing some cases and do the codes I linked do that in all of them?
• Are there any field in the Window component that can't be used to modify the state of the window, only at creation?

[alice-i-cecile]

There's some subtle additional behavioral differences on most platforms: it may be worth distinguishing between the different fullscreen modes more clearly.

[Selene-Amanita]

I 'm not sure what the difference between the different fullscreen variants are tbh, from my understanding (I just tested):

• Borderless fullscreen takes the desktop's resolution and simply applies it to the window
• SizedFullscreen changes the desktop's resolution to match as closely as possible the window's, then applies it to the window
• Fullscreen changes the desktop's resolution to take the biggest one available, then applies it to the window

I would appreciate help from someone who understands it to confirm what I understood and write accurate documentation.

[alice-i-cecile]

@inodentry this seems like the sort of thing you have a good handle on :) This article lines up with my understanding though: https://helpdeskgeek.com/help-desk/windowed-fullscreen-and-borderless-modes-which-one-is-best/

Basically, "true full screen" is an old-school approach that provides dedicated resource allocation but makes swapping programs more expensive. IIRC these days most OSes have other tools to determine priority though.

[djeedai]

These days borderless window should be the recommended one. It's on par performance-wise will Fullscreen, but as @alice-i-cecile mentioned provides a much better app swap experience.

[Selene-Amanita]

Tried to clarify fullscreen with fa0c745

Again I stayed "general" as some behaviours I encountered seemed more like bugs than features: #8921 .

[Selene-Amanita]

Added documentation to link PrimaryWindow to WindowPlugin: d36b553

(every time I want to configure the primary window I look for the marker component in the doc and I have to think after that)

[djeedai]

Minor typos so Approved. Left some comments for discussion though, but are probably out of scope of this documentation work.

Thanks!

[djeedai]

I don't understand that sentence.

[Selene-Amanita]

I should just rewrite it "Ratio of physical size to requested size" (respectively logical)

physical/requested/logical is explained above in the doc of WindowResolution

I didn't modify that explanation, mainly because I'm not sure I understand it, but I feel like it could be made more clear!

[Selene-Amanita]

Partially resolved by a36128c (?) but WindowResolution's doc should probably be rewritten.

[djeedai]

Oh I think I understand now, nevermind.

Maybe something not involving the OS? It's kind of a detail; the user only cares that's it's automatically set, no?

Suggested change

	/// Set by the operating system depending on monitor pixel densities.
	/// Set automatically depending on the pixel density of the screen.

[Selene-Amanita]

Committed your change but keeping the conversation open to clarify WindowResolution's doc

[djeedai]

Thanks

[Selene-Amanita]

After reading more of the code and pocking around with the scale_factor_override example, here's my attempt to clarify WindowResolution's documentation: 5a30319

I tried to stay somewhat general and focus more on the intent than the actual behaviour, because I feel like some behaviours are not necessarily intended, for example in the scale_factor_override example if the scale factor is too big to fit on the screen, the logical size will change to match the ratio of height to width* but the physical size will continue to increase despite the window not taking all of that space, I feel like this is not intended for example. See #8921 for more examples.

*(which is what I'm talking about in The requested size is not kept in memory, for example changing the scale factor one way and changing it back after might not get the original size back., I didn't stay general in that part)

Edit: (changed that last part to: The requested size is not kept in memory, for example requesting a size too big for the screen, making the logical size different from the requested size, then setting a scale factor that makes the previous requested size within the limits of the screen will not get back that previous requested size.)

[djeedai]

Looks good to me, thanks a lot for all the experimentations and efforts to make those docs correct. Couple of minor points but I wouldn't block any merge on them.

[djeedai]

Actually I think "client area" was the proper term, at least on Windows.

[Selene-Amanita]

Reverted that part. I deleted it in the WindowResolution's methods but not in the Window's ones anyway...

[alice-i-cecile]

Very nice: these are a substantial improvement. The cross-linking is also nice!