From 650909244eee51b4fd70389538c6b784ccf005c7 Mon Sep 17 00:00:00 2001
From: Axel Viala <axel.viala@darnuria.eu>
Date: Wed, 4 Jun 2014 14:45:56 +0200
Subject: [PATCH 1/3] Add code example to std::os::getenv for unix.

---
 src/libstd/os.rs | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/src/libstd/os.rs b/src/libstd/os.rs
index fa0116b248223..15fd2cb8f12c5 100644
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -277,6 +277,16 @@ pub fn env_as_bytes() -> Vec<(Vec<u8>,Vec<u8>)> {
 /// # Failure
 ///
 /// Fails if `n` has any interior NULs.
+///
+/// # Example
+///
+/// ```rust
+/// let key = "HOME";
+/// match std::os::getenv(key) {
+///     Some(val) => println!("{}: {}", key, val),
+///     None => println!("{} is not defined in the environnement.", key)
+/// }
+/// ```
 pub fn getenv(n: &str) -> Option<String> {
     getenv_as_bytes(n).map(|v| str::from_utf8_lossy(v.as_slice()).to_string())
 }

From f377dfe5acfd7023d535a94cfe9466276affc6da Mon Sep 17 00:00:00 2001
From: Axel Viala <axel.viala@darnuria.eu>
Date: Wed, 4 Jun 2014 16:33:25 +0200
Subject: [PATCH 2/3] Adding examples and possible failures for getcwd.

For both window and unix platforms.
---
 src/libstd/os.rs | 38 ++++++++++++++++++++++++++++++++++++--
 1 file changed, 36 insertions(+), 2 deletions(-)

diff --git a/src/libstd/os.rs b/src/libstd/os.rs
index 15fd2cb8f12c5..eae4ca422013c 100644
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -66,7 +66,24 @@ pub fn close(fd: int) -> int {
 pub static TMPBUF_SZ : uint = 1000u;
 static BUF_BYTES : uint = 2048u;
 
-/// Returns the current working directory.
+/// Returns the current working directory as a Path.
+///
+/// # Failure
+///
+/// Fails if the current working directory value is invalid:
+/// Possibles cases:
+///
+/// * Current directory does not exist.
+/// * There are insufficient permissions to access the current directory.
+///
+/// # Example
+///
+/// ```rust
+/// // We assume that we are in a valid directory like "/home".
+/// let current_working_directory = std::os::getcwd();
+/// println!("The current directory is {}", current_working_directory.display());
+/// // /home
+/// ```
 #[cfg(unix)]
 pub fn getcwd() -> Path {
     use c_str::CString;
@@ -80,7 +97,24 @@ pub fn getcwd() -> Path {
     }
 }
 
-/// Returns the current working directory.
+/// Returns the current working directory as a Path.
+///
+/// # Failure
+///
+/// Fails if the current working directory value is invalid.
+/// Possibles cases:
+///
+/// * Current directory does not exist.
+/// * There are insufficient permissions to access the current directory.
+///
+/// # Example
+///
+/// ```rust
+/// // We assume that we are in a valid directory like "C:\\Windows".
+/// let current_working_directory = std::os::getcwd();
+/// println!("The current directory is {}", current_working_directory.display());
+/// // C:\\Windows
+/// ```
 #[cfg(windows)]
 pub fn getcwd() -> Path {
     use libc::DWORD;

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 3/3] 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 eae4ca422013c..a93be701f531b 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();