From 3a898437671796e865db8b7ba37dd90ce8f2fbed Mon Sep 17 00:00:00 2001
From: Alex Butler <alexheretic@gmail.com>
Date: Wed, 21 Jun 2017 20:10:23 +0100
Subject: [PATCH] Add `WINIT_UNIX_BACKEND` documentation

---
 src/lib.rs                | 10 +++++++++-
 src/platform/linux/mod.rs | 12 +++++++-----
 src/window.rs             | 20 ++++++++++++++++++--
 3 files changed, 34 insertions(+), 8 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index d4b91c40c8..291bfb37ed 100644
--- a/src/lib.rs
+++ b/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,
 }
diff --git a/src/platform/linux/mod.rs b/src/platform/linux/mod.rs
index 909ca1e30c..af431a10a2 100644
--- a/src/platform/linux/mod.rs
+++ b/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)]
diff --git a/src/window.rs b/src/window.rs
index 94c677b073..d93ee4704a 100644
--- a/src/window.rs
+++ b/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,6 +320,14 @@ 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();
@@ -327,6 +335,14 @@ pub fn get_available_monitors() -> AvailableMonitorsIter {
 }
 
 /// 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())