---

yaml
---
r: 220614
b: refs/heads/tmp
c: 092f4ed
h: refs/heads/master
v: v3

Author: steveklabnik

[refs]

@@ -25,7 +25,7 @@ refs/tags/0.11.0: e1247cb1d0d681be034adb4b558b5a0c0d5720f9
 refs/tags/0.12.0: f0c419429ef30723ceaf6b42f9b5a2aeb5d2e2d1
 refs/heads/beta: c8bab9d06a179028a0d5129aa62f09d694d9cc49
 refs/tags/1.0.0-alpha: e42bd6d93a1d3433c486200587f8f9e12590a4d7
-refs/heads/tmp: ff664f3c6cc0b9b530406c2ffb380040b4c4fc88
+refs/heads/tmp: 092f4ed2de83884661373b6ce7cd217a7b9860ee
 refs/tags/1.0.0-alpha.2: 4c705f6bc559886632d3871b04f58aab093bfa2f
 refs/tags/homu-tmp: 1b28ffa5216c845d1cef6b0cb3e5ac7db12025d0
 refs/tags/1.0.0-beta: 8cbb92b53468ee2b0c2d3eeb8567005953d40828

branches/tmp/src/libstd/io/mod.rs

@@ -692,17 +692,38 @@ pub trait Write {
     }
 }
 
-/// An object implementing `Seek` internally has some form of cursor which can
-/// be moved within a stream of bytes.
+/// The `Seek` trait provides a cursor which can be moved within a stream of
+/// bytes.
 ///
 /// The stream typically has a fixed size, allowing seeking relative to either
 /// end or the current offset.
+///
+/// # Examples
+///
+/// [`File`][file]s implement `Seek`:
+///
+/// [file]: ../std/fs/struct.File.html
+///
+/// ```
+/// use std::io;
+/// use std::fs::File;
+/// use std::io::Seek;
+/// use std::io::SeekFrom;
+///
+/// # fn foo() -> io::Result<()> {
+/// let mut f = try!(File::open("foo.txt"));
+///
+/// // move the cursor 42 bytes from the start of the file
+/// f.seek(SeekFrom::Start(42)).unwrap();
+/// # Ok(())
+/// # }
+/// ```
 #[stable(feature = "rust1", since = "1.0.0")]
 pub trait Seek {
-    /// Seek to an offset, in bytes, in a stream
+    /// Seek to an offset, in bytes, in a stream.
     ///
-    /// A seek beyond the end of a stream is allowed, but seeking before offset
-    /// 0 is an error.
+    /// A seek beyond the end of a stream is allowed, but implementation
+    /// defined.
     ///
     /// The behavior when seeking past the end of the stream is implementation
     /// defined.
@@ -712,7 +733,7 @@ pub trait Seek {
     ///
     /// # Errors
     ///
-    /// Seeking to a negative offset is considered an error
+    /// Seeking to a negative offset is considered an error.
     #[stable(feature = "rust1", since = "1.0.0")]
     fn seek(&mut self, pos: SeekFrom) -> Result<u64>;
 }