Add WINIT_UNIX_BACKEND documentation

src/lib.rs

@@ -1,4 +1,4 @@
-//! Winit allows you to build a window on as many platforms as possible. 
+//! Winit allows you to build a window on as many platforms as possible.
 //!
 //! # Building a window
 //!
@@ -181,6 +181,14 @@ pub struct ButtonId(u32);
 /// Provides a way to retreive events from the windows that were registered to it.
 ///
 /// To wake up an `EventsLoop` from a another thread, see the `EventsLoopProxy` docs.
+///
+/// Usage will result in display backend initialisation, this can be controlled on linux
+/// using an environment variable `WINIT_UNIX_BACKEND`.
+/// > Legal values are `x11` and `wayland`. If this variable is set only the named backend
+/// > will be tried by winit. If it is not set, winit will try to connect to a wayland connection,
+/// > and if it fails will fallback on x11.
+/// >
+/// > If this variable is set with any other value, winit will panic.
 pub struct EventsLoop {
     events_loop: platform::EventsLoop,
 }

src/platform/linux/mod.rs

@@ -16,11 +16,13 @@ mod dlopen;
 pub mod wayland;
 pub mod x11;
 
-/// Environment variable that indicates a backend preference
-/// `WINIT_UNIX_BACKEND=x11` : Will try to use an X11 backend
-/// `WINIT_UNIX_BACKEND=wayland` : Will try to use a wayland backend
-/// When the variable is present the indicated backend will not fallback to another
-/// (Current default behaviour, without the env var, is try wayland then fallback to X)
+/// Environment variable specifying which backend should be used on unix platform.
+///
+/// Legal values are x11 and wayland. If this variable is set only the named backend
+/// will be tried by winit. If it is not set, winit will try to connect to a wayland connection,
+/// and if it fails will fallback on x11.
+///
+/// If this variable is set with any other value, winit will panic.
 const BACKEND_PREFERENCE_ENV_VAR: &str = "WINIT_UNIX_BACKEND";
 
 #[derive(Clone, Default)]

src/window.rs

@@ -30,7 +30,7 @@ impl WindowBuilder {
         self.window.dimensions = Some((width, height));
         self
     }
-    
+
     /// Sets a minimum dimension size for the window
     ///
     /// Width and height are in pixels.
@@ -197,7 +197,7 @@ impl Window {
     pub fn get_inner_size(&self) -> Option<(u32, u32)> {
         self.window.get_inner_size()
     }
-    
+
     /// Returns the size in points of the client area of the window.
     ///
     /// The client area is the content of the window, excluding the title bar and borders.
@@ -320,13 +320,29 @@ impl Iterator for AvailableMonitorsIter {
 }
 
 /// Returns the list of all available monitors.
+///
+/// Usage will result in display backend initialisation, this can be controlled on linux
+/// using an environment variable `WINIT_UNIX_BACKEND`.
+/// > Legal values are `x11` and `wayland`. If this variable is set only the named backend
+/// > will be tried by winit. If it is not set, winit will try to connect to a wayland connection,
+/// > and if it fails will fallback on x11.
+/// >
+/// > If this variable is set with any other value, winit will panic.
 #[inline]
 pub fn get_available_monitors() -> AvailableMonitorsIter {
     let data = platform::get_available_monitors();
     AvailableMonitorsIter{ data: data.into_iter() }
 }
 
 /// Returns the primary monitor of the system.
+///
+/// Usage will result in display backend initialisation, this can be controlled on linux
+/// using an environment variable `WINIT_UNIX_BACKEND`.
+/// > Legal values are `x11` and `wayland`. If this variable is set only the named backend
+/// > will be tried by winit. If it is not set, winit will try to connect to a wayland connection,
+/// > and if it fails will fallback on x11.
+/// >
+/// > If this variable is set with any other value, winit will panic.
 #[inline]
 pub fn get_primary_monitor() -> MonitorId {
     MonitorId(platform::get_primary_monitor())