std: docstring fixes in io::file

1 files changed, 259 insertions, 239 deletions

diff --git a/src/libstd/rt/io/file.rs b/src/libstd/rt/io/file.rs
index 75798837aff..2a9b71db90b 100644
--- a/src/libstd/rt/io/file.rs
+++ b/src/libstd/rt/io/file.rs
@@ -8,21 +8,6 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-use prelude::*;
-use super::support::PathLike;
-use super::{Reader, Writer, Seek};
-use super::{SeekStyle,SeekSet, SeekCur, SeekEnd,
-            Open, Read, Write, Create, ReadWrite};
-use rt::rtio::{RtioFileStream, IoFactory, IoFactoryObject};
-use rt::io::{io_error, read_error, EndOfFile,
-            FileMode, FileAccess, FileStat, IoError,
-            PathAlreadyExists, PathDoesntExist,
-            MismatchedFileTypeForOperation, ignore_io_error};
-use rt::local::Local;
-use option::{Some, None};
-use path::Path;
-use super::super::test::*;
-
 /*! Synchronous File I/O
 
 This module provides a set of functions and traits for working
@@ -44,52 +29,66 @@ possible, the `{FileInfo, DirectoryInfo}` preserve the same semantics as their
 free function counterparts.
 */
 
-/*! Open a file for reading/writing, as indicated by `path`.
-
-# Example
-
-    use std;
-    use std::path::Path;
-    use std::rt::io::support::PathLike;
-    use std::rt::io::file::open;
-    use std::rt::io::{FileMode, FileAccess};
-
-    let p = &Path("/some/file/path.txt");
-    
-    do io_error::cond.trap(|_| {
-        // hoo-boy...
-    }).inside {
-        let stream = match open(p, Create, ReadWrite) {
-            Some(s) => s,
-            None => fail!("whoops! I'm sure this raised, anyways..");
-        }
-        // do some stuff with that stream
-
-        // the file stream will be closed at the end of this block
-    }
-    // ..
-
-`FileMode` and `FileAccess` provide information about the permissions
-context in which a given stream is created. More information about them
-can be found in `std::rt::io`'s docs.
-
-Note that, with this function, a `FileStream` is returned regardless of
-the access-limitations indicated by `FileAccess` (e.g. calling `write` on a
-`FileStream` opened as `ReadOnly` will raise an `io_error` condition at runtime). If you
-desire a more-correctly-constrained interface to files, use the
-`{open_stream, open_reader, open_writer}` methods that are a part of `FileInfo`
-
-# Errors
-
-This function will raise an `io_error` condition under a number of different circumstances,
-to include but not limited to:
+use prelude::*;
+use super::support::PathLike;
+use super::{Reader, Writer, Seek};
+use super::{SeekStyle,SeekSet, SeekCur, SeekEnd,
+            Open, Read, Write, Create, ReadWrite};
+use rt::rtio::{RtioFileStream, IoFactory, IoFactoryObject};
+use rt::io::{io_error, read_error, EndOfFile,
+            FileMode, FileAccess, FileStat, IoError,
+            PathAlreadyExists, PathDoesntExist,
+            MismatchedFileTypeForOperation, ignore_io_error};
+use rt::local::Local;
+use option::{Some, None};
+use path::Path;
+use super::super::test::*;
 
-* Opening a file that already exists with `FileMode` of `Create` or vice versa (e.g.
-  opening a non-existant file with `FileMode` or `Open`)
-* Attempting to open a file with a `FileAccess` that the user lacks permissions
-  for
-* Filesystem-level errors (full disk, etc)
-*/
+/// Open a file for reading/writing, as indicated by `path`.
+/// 
+/// # Example
+/// 
+///     use std;
+///     use std::path::Path;
+///     use std::rt::io::support::PathLike;
+///     use std::rt::io::file::open;
+///     use std::rt::io::{FileMode, FileAccess};
+/// 
+///     let p = &Path("/some/file/path.txt");
+///     
+///     do io_error::cond.trap(|_| {
+///         // hoo-boy...
+///     }).inside {
+///         let stream = match open(p, Create, ReadWrite) {
+///             Some(s) => s,
+///             None => fail!("whoops! I'm sure this raised, anyways..");
+///         }
+///         // do some stuff with that stream
+/// 
+///         // the file stream will be closed at the end of this block
+///     }
+///     // ..
+/// 
+/// `FileMode` and `FileAccess` provide information about the permissions
+/// context in which a given stream is created. More information about them
+/// can be found in `std::rt::io`'s docs.
+/// 
+/// Note that, with this function, a `FileStream` is returned regardless of
+/// the access-limitations indicated by `FileAccess` (e.g. calling `write` on a
+/// `FileStream` opened as `ReadOnly` will raise an `io_error` condition at runtime). If you
+/// desire a more-correctly-constrained interface to files, use the
+/// `{open_stream, open_reader, open_writer}` methods that are a part of `FileInfo`
+/// 
+/// # Errors
+/// 
+/// This function will raise an `io_error` condition under a number of different circumstances,
+/// to include but not limited to:
+/// 
+/// * Opening a file that already exists with `FileMode` of `Create` or vice versa (e.g.
+///   opening a non-existant file with `FileMode` or `Open`)
+/// * Attempting to open a file with a `FileAccess` that the user lacks permissions
+///   for
+/// * Filesystem-level errors (full disk, etc)
 pub fn open<P: PathLike>(path: &P,
                          mode: FileMode,
                          access: FileAccess
@@ -110,29 +109,28 @@ pub fn open<P: PathLike>(path: &P,
     }
 }
 
-/*! Unlink a file from the underlying filesystem.
-
-# Example
-
-    use std;
-    use std::path::Path;
-    use std::rt::io::support::PathLike;
-    use std::rt::io::file::unlink;
-
-    let p = &Path("/some/file/path.txt");
-    unlink(p);
-    // if we made it here without failing, then the
-    // unlink operation was successful
-
-Note that, just because an unlink call was successful, it is not
-guaranteed that a file is immediately deleted (e.g. depending on
-platform, other open file descriptors may prevent immediate removal)
-
-# Errors
-
-This function will raise an `io_error` condition if the user lacks permissions to
-remove the file or if some other filesystem-level error occurs
-*/
+/// Unlink a file from the underlying filesystem.
+/// 
+/// # Example
+/// 
+///     use std;
+///     use std::path::Path;
+///     use std::rt::io::support::PathLike;
+///     use std::rt::io::file::unlink;
+/// 
+///     let p = &Path("/some/file/path.txt");
+///     unlink(p);
+///     // if we made it here without failing, then the
+///     // unlink operation was successful
+/// 
+/// Note that, just because an unlink call was successful, it is not
+/// guaranteed that a file is immediately deleted (e.g. depending on
+/// platform, other open file descriptors may prevent immediate removal)
+/// 
+/// # Errors
+/// 
+/// This function will raise an `io_error` condition if the user lacks permissions to
+/// remove the file or if some other filesystem-level error occurs
 pub fn unlink<P: PathLike>(path: &P) {
     let unlink_result = unsafe {
         let io: *mut IoFactoryObject = Local::unsafe_borrow();
@@ -146,24 +144,23 @@ pub fn unlink<P: PathLike>(path: &P) {
     }
 }
 
-/*! Create a new, empty directory at the provided path
-
-# Example
-
-    use std;
-    use std::path::Path;
-    use std::rt::io::support::PathLike;
-    use std::rt::io::file::mkdir;
-
-    let p = &Path("/some/dir");
-    mkdir(p);
-    // If we got here, our directory exists! Horray!
-
-# Errors
-
-This call will raise an `io_error` condition if the user lacks permissions to make a
-new directory at the provided path, or if the directory already exists
-*/
+/// Create a new, empty directory at the provided path
+/// 
+/// # Example
+/// 
+///     use std;
+///     use std::path::Path;
+///     use std::rt::io::support::PathLike;
+///     use std::rt::io::file::mkdir;
+/// 
+///     let p = &Path("/some/dir");
+///     mkdir(p);
+///     // If we got here, our directory exists! Horray!
+/// 
+/// # Errors
+/// 
+/// This call will raise an `io_error` condition if the user lacks permissions to make a
+/// new directory at the provided path, or if the directory already exists
 pub fn mkdir<P: PathLike>(path: &P) {
     let mkdir_result = unsafe {
         let io: *mut IoFactoryObject = Local::unsafe_borrow();
@@ -177,24 +174,23 @@ pub fn mkdir<P: PathLike>(path: &P) {
     }
 }
 
-/*! Remove an existing, empty directory
-
-# Example
-
-    use std;
-    use std::path::Path;
-    use std::rt::io::support::PathLike;
-    use std::rt::io::file::rmdir;
-
-    let p = &Path("/some/dir");
-    rmdir(p);
-    // good riddance, you mean ol' directory
-
-# Errors
-
-This call will raise an `io_error` condition if the user lacks permissions to remove the
-directory at the provided path, or if the directory isn't empty
-*/
+/// Remove an existing, empty directory
+/// 
+/// # Example
+/// 
+///     use std;
+///     use std::path::Path;
+///     use std::rt::io::support::PathLike;
+///     use std::rt::io::file::rmdir;
+/// 
+///     let p = &Path("/some/dir");
+///     rmdir(p);
+///     // good riddance, you mean ol' directory
+/// 
+/// # Errors
+/// 
+/// This call will raise an `io_error` condition if the user lacks permissions to remove the
+/// directory at the provided path, or if the directory isn't empty
 pub fn rmdir<P: PathLike>(path: &P) {
     let rmdir_result = unsafe {
         let io: *mut IoFactoryObject = Local::unsafe_borrow();
@@ -208,43 +204,42 @@ pub fn rmdir<P: PathLike>(path: &P) {
     }
 }
 
-/*! Get information on the file, directory, etc at the provided path
-
-Given a `rt::io::support::PathLike`, query the file system to get
-information about a file, directory, etc.
-
-Returns a `Some(std::rt::io::PathInfo)` on success
-
-# Example
-
-    use std;
-    use std::path::Path;
-    use std::rt::io::support::PathLike;
-    use std::rt::io::file::stat;
-
-    let p = &Path("/some/file/path.txt");
-
-    do io_error::cond.trap(|_| {
-        // hoo-boy...
-    }).inside {
-        let info = match stat(p) {
-            Some(s) => s,
-            None => fail!("whoops! I'm sure this raised, anyways..");
-        }
-        if stat.is_file {
-            // just imagine the possibilities ...
-        }
-
-        // the file stream will be closed at the end of this block
-    }
-    // ..
-
-# Errors
-
-This call will raise an `io_error` condition if the user lacks the requisite
-permissions to perform a `stat` call on the given path or if there is no
-entry in the filesystem at the provided path.
-*/
+/// Get information on the file, directory, etc at the provided path
+/// 
+/// Given a `rt::io::support::PathLike`, query the file system to get
+/// information about a file, directory, etc.
+/// 
+/// Returns a `Some(std::rt::io::PathInfo)` on success
+/// 
+/// # Example
+/// 
+///     use std;
+///     use std::path::Path;
+///     use std::rt::io::support::PathLike;
+///     use std::rt::io::file::stat;
+/// 
+///     let p = &Path("/some/file/path.txt");
+/// 
+///     do io_error::cond.trap(|_| {
+///         // hoo-boy...
+///     }).inside {
+///         let info = match stat(p) {
+///             Some(s) => s,
+///             None => fail!("whoops! I'm sure this raised, anyways..");
+///         }
+///         if stat.is_file {
+///             // just imagine the possibilities ...
+///         }
+/// 
+///         // the file stream will be closed at the end of this block
+///     }
+///     // ..
+/// 
+/// # Errors
+/// 
+/// This call will raise an `io_error` condition if the user lacks the requisite
+/// permissions to perform a `stat` call on the given path or if there is no
+/// entry in the filesystem at the provided path.
 pub fn stat<P: PathLike>(path: &P) -> Option<FileStat> {
     let open_result = unsafe {
         let io: *mut IoFactoryObject = Local::unsafe_borrow();
@@ -261,8 +256,31 @@ pub fn stat<P: PathLike>(path: &P) -> Option<FileStat> {
     }
 }
 
-/*! Retrieve a vector containing all entries within a provided directory
-*/
+/// Retrieve a vector containing all entries within a provided directory
+///
+/// # Example
+///
+///     use std;
+///     use std::path::Path;
+///     use std::rt::io::support::PathLike;
+///     use std::rt::io::file::readdir;
+///
+///     fn visit_dirs(dir: &Path, cb: &fn(&Path)) {
+///         if dir.is_dir() {
+///             let contents = dir.readdir();
+///             for entry in contents.iter() {
+///                 if entry.is_dir() { visit_dirs(entry, cb); }
+///                 else { cb(entry); }
+///             }
+///         }
+///         else { fail!("nope"); }
+///     }
+///
+/// # Errors
+///
+/// Will raise an `io_error` condition if the provided `path` doesn't exist,
+/// the process lacks permissions to view the contents or if the `path` points
+/// at a non-directory file
 pub fn readdir<P: PathLike>(path: &P) -> Option<~[Path]> {
     let readdir_result = unsafe {
         let io: *mut IoFactoryObject = Local::unsafe_borrow();
@@ -279,10 +297,9 @@ pub fn readdir<P: PathLike>(path: &P) -> Option<~[Path]> {
     }
 }
 
-/*! Constrained version of `FileStream` that only exposes read-specific operations.
-
-Can be retreived via `FileInfo.open_reader()`.
-*/
+/// Constrained version of `FileStream` that only exposes read-specific operations.
+///
+/// Can be retreived via `FileInfo.open_reader()`.
 pub struct FileReader { priv stream: FileStream }
 
 /// a `std::rt::io::Reader` trait impl for file I/O.
@@ -307,10 +324,9 @@ impl Seek for FileReader {
     }
 }
 
-/*! Constrained version of `FileStream` that only exposes write-specific operations.
-
-Can be retreived via `FileInfo.open_writer()`.
-*/
+/// Constrained version of `FileStream` that only exposes write-specific operations.
+/// 
+/// Can be retreived via `FileInfo.open_writer()`.
 pub struct FileWriter { priv stream: FileStream }
 
 /// a `std::rt::io::Writer` trait impl for file I/O.
@@ -335,19 +351,18 @@ impl Seek for FileWriter {
     }
 }
 
-/*! Unconstrained file access type that exposes read and write operations
-
-Can be retreived via `file::open()` and `FileInfo.open_stream()`.
-
-# Errors
-
-This type will raise an io_error condition if operations are attempted against
-it for which its underlying file descriptor was not configured at creation
-time, via the `FileAccess` parameter to `file::open()`.
-
-For this reason, it is best to use the access-constrained wrappers that are
-exposed via `FileInfo.open_reader()` and `FileInfo.open_writer()`.
-*/
+/// Unconstrained file access type that exposes read and write operations
+/// 
+/// Can be retreived via `file::open()` and `FileInfo.open_stream()`.
+/// 
+/// # Errors
+/// 
+/// This type will raise an io_error condition if operations are attempted against
+/// it for which its underlying file descriptor was not configured at creation
+/// time, via the `FileAccess` parameter to `file::open()`.
+/// 
+/// For this reason, it is best to use the access-constrained wrappers that are
+/// exposed via `FileInfo.open_reader()` and `FileInfo.open_writer()`.
 pub struct FileStream {
     fd: ~RtioFileStream,
     last_nread: int,
@@ -435,12 +450,11 @@ pub trait FileSystemInfo {
     /// later creates
     fn get_path<'a>(&'a self) -> &'a Path;
 
-    /*! Get information on the file, directory, etc at the provided path
-
-    Consult the `file::stat` documentation for more info.
-
-    This call preserves identical runtime/error semantics
-    */
+    /// Get information on the file, directory, etc at the provided path
+    ///
+    /// Consult the `file::stat` documentation for more info.
+    ///
+    /// This call preserves identical runtime/error semantics with `file::stat`
     fn stat(&self) -> Option<FileStat> {
         stat(self.get_path())
     }
@@ -459,37 +473,40 @@ pub trait FileSystemInfo {
 
 }
 
-/*! Represents a file, whose underlying path may or may not be valid
-
-# Example
-
-* Check if a file exists, reading from it if so
-
-    use std;
-    use std::path::Path;
-    use std::rt::io::file::{FileInfo, FileReader};
-
-    let f = &Path("/some/file/path.txt");
-    if f.exists() {
-        let reader = f.open_reader(Open);
-        let mut mem = [0u8, 8*64000];
-        reader.read(mem);
-        // ...
-    }
-
-* Is the given path a file?
-
-   let f = get_file_path_from_wherever();
-   match f.is_file() {
-       true => doing_something_with_a_file(f),
-       _ => {}
-   }
-*/
+/// Represents a file, whose underlying path may or may not be valid
+/// 
+/// # Example
+/// 
+/// * Check if a file exists, reading from it if so
+/// 
+///     use std;
+///     use std::path::Path;
+///     use std::rt::io::file::{FileInfo, FileReader};
+/// 
+///     let f = &Path("/some/file/path.txt");
+///     if f.exists() {
+///         let reader = f.open_reader(Open);
+///         let mut mem = [0u8, 8*64000];
+///         reader.read(mem);
+///         // ...
+///     }
+/// 
+/// * Is the given path a file?
+/// 
+///    let f = get_file_path_from_wherever();
+///    match f.is_file() {
+///        true => doing_something_with_a_file(f),
+///        _ => {}
+///    }
 pub trait FileInfo : FileSystemInfo {
     /// Whether the underlying implemention (be it a file path,
     /// or something else) points at a "regular file" on the FS. Will return
     /// false for paths to non-existent locations or directories or
     /// other non-regular files (named pipes, etc).
+    ///
+    /// # Errors
+    ///
+    /// Will not raise a condition
     fn is_file(&self) -> bool {
         match ignore_io_error(|| self.stat()) {
             Some(s) => s.is_file,
@@ -549,39 +566,42 @@ impl FileSystemInfo for Path {
 /// `FileInfo` implementation for `Path`s
 impl FileInfo for Path { }
 
-/*! Represents a directory, whose underlying path may or may not be valid
-
-# Example
-
-* Check if a directory exists, `mkdir`'ing it if not
-
-    use std;
-    use std::path::Path;
-    use std::rt::io::file::{DirectoryInfo};
-
-    let dir = &Path("/some/dir");
-    if !dir.exists() {
-        dir.mkdir();
-    }
-
-* Is the given path a directory? If so, iterate on its contents
-
-    fn visit_dirs(dir: &Path, cb: &fn(&Path)) {
-        if dir.is_dir() {
-            let contents = dir.readdir();
-            for entry in contents.iter() {
-                if entry.is_dir() { visit_dirs(entry, cb); }
-                else { cb(entry); }
-            }
-        }
-        else { fail!("nope"); }
-    }
-*/
+/// Represents a directory, whose underlying path may or may not be valid
+/// 
+/// # Example
+/// 
+/// * Check if a directory exists, `mkdir`'ing it if not
+/// 
+///     use std;
+///     use std::path::Path;
+///     use std::rt::io::file::{DirectoryInfo};
+/// 
+///     let dir = &Path("/some/dir");
+///     if !dir.exists() {
+///         dir.mkdir();
+///     }
+/// 
+/// * Is the given path a directory? If so, iterate on its contents
+/// 
+///     fn visit_dirs(dir: &Path, cb: &fn(&Path)) {
+///         if dir.is_dir() {
+///             let contents = dir.readdir();
+///             for entry in contents.iter() {
+///                 if entry.is_dir() { visit_dirs(entry, cb); }
+///                 else { cb(entry); }
+///             }
+///         }
+///         else { fail!("nope"); }
+///     }
 trait DirectoryInfo : FileSystemInfo {
     /// Whether the underlying implemention (be it a file path,
     /// or something else) is pointing at a directory in the underlying FS.
     /// Will return false for paths to non-existent locations or if the item is
     /// not a directory (eg files, named pipes, links, etc)
+    ///
+    /// # Errors
+    ///
+    /// Will not raise a condition
     fn is_dir(&self) -> bool {
         match ignore_io_error(|| self.stat()) {
             Some(s) => s.is_dir,