Adjusted heading and created dedicated section in std::io docs

[rust.git] / src / libstd / io / mod.rs

diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index 7be0f467ac9ff8b4b39c6bd90c47608bf7529846..b5ba6ff54c0e3b7d32b5fcb9ed1b450aae48562d 100644 (file)
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -238,6 +238,15 @@
 //!
 //! [result]: type.Result.html
 //! [try]: ../macro.try!.html
+//!
+//! ## Platform-specific behavior
+//!
+//! Many I/O functions throughout the standard library are documented to indicate
+//! what various library or syscalls they are delegated to. This is done to help
+//! applications both understand what's happening under the hood as well as investigate
+//! any possibly unclear semantics. Note, however, that this is informative, not a binding
+//! contract. The implementation of many of these functions are subject to change over
+//! time and may call fewer or more syscalls/library functions.
 
 #![stable(feature = "rust1", since = "1.0.0")]
 
@@ -1171,7 +1180,7 @@ pub enum SeekFrom {
     /// Set the offset to the size of this object plus the specified number of
     /// bytes.
     ///
-    /// It is possible to seek beyond the end of an object, but is an error to
+    /// It is possible to seek beyond the end of an object, but it's an error to
     /// seek before byte 0.
     #[stable(feature = "rust1", since = "1.0.0")]
     End(i64),
@@ -1179,7 +1188,7 @@ pub enum SeekFrom {
     /// Set the offset to the current position plus the specified number of
     /// bytes.
     ///
-    /// It is possible to seek beyond the end of an object, but is an error to
+    /// It is possible to seek beyond the end of an object, but it's an error to
     /// seek before byte 0.
     #[stable(feature = "rust1", since = "1.0.0")]
     Current(i64),
@@ -1983,7 +1992,7 @@ fn bench_read_to_end(b: &mut test::Bencher) {
         b.iter(|| {
             let mut lr = repeat(1).take(10000000);
             let mut vec = Vec::with_capacity(1024);
-            super::read_to_end(&mut lr, &mut vec);
+            super::read_to_end(&mut lr, &mut vec)
         });
     }
 }