From 85adc09b19a437dab822fe67db908207aaa541b9 Mon Sep 17 00:00:00 2001
From: Axel Viala <axel.viala@darnuria.eu>
Date: Thu, 5 Jun 2014 17:36:15 +0200
Subject: [PATCH] Improve documentation on std::os::env.

---
 src/libstd/os.rs | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/src/libstd/os.rs b/src/libstd/os.rs
index eae4ca42201..a93be701f53 100644
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -206,11 +206,20 @@ fn with_env_lock<T>(f: || -> T) -> T {
     }
 }
 
-/// Returns a vector of (variable, value) pairs for all the environment
-/// variables of the current process.
+/// Returns a vector of (variable, value) pairs as a Vec<(String, String)>,
+/// for all the environment variables of the current process.
 ///
 /// Invalid UTF-8 bytes are replaced with \uFFFD. See `str::from_utf8_lossy()`
 /// for details.
+///
+/// # Example
+///
+/// ```rust
+/// // We will iterate through the references to the element returned by std::os::env();
+/// for &(ref key, ref value) in std::os::env().iter() {
+///     println!("'{}': '{}'", key, value );
+/// }
+/// ```
 pub fn env() -> Vec<(String,String)> {
     env_as_bytes().move_iter().map(|(k,v)| {
         let k = str::from_utf8_lossy(k.as_slice()).to_string();