From: Nathan Date: Tue, 1 Dec 2015 02:23:19 +0000 (-0500) Subject: Adjusted heading and created dedicated section in std::io docs X-Git-Url: https://git.lizzy.rs/?a=commitdiff_plain;h=3e9d5fea48f616c1052d38e67b18e98624210867;p=rust.git Adjusted heading and created dedicated section in std::io docs --- diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index 1819a308b3c..635ed91f35d 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -715,7 +715,7 @@ pub fn path(&self) -> PathBuf { self.0.path() } /// This function will not traverse symlinks if this entry points at a /// symlink. /// - /// # Platform behavior + /// # Platform-specific behavior /// /// On Windows this function is cheap to call (no extra system calls /// needed), but on Unix platforms this function is the equivalent of @@ -730,7 +730,7 @@ pub fn metadata(&self) -> io::Result { /// This function will not traverse symlinks if this entry points at a /// symlink. /// - /// # Platform behavior + /// # Platform-specific behavior /// /// On Windows and most Unix platforms this function is free (no extra /// system calls needed), but some Unix platforms may require the equivalent @@ -758,12 +758,12 @@ fn as_inner(&self) -> &fs_imp::DirEntry { &self.0 } /// guarantee that the file is immediately deleted (e.g. depending on /// platform, other open file descriptors may prevent immediate removal). /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `unlink` function on Unix /// and the `DeleteFile` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -794,12 +794,12 @@ pub fn remove_file>(path: P) -> io::Result<()> { /// This function will traverse symbolic links to query information about the /// destination file. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `stat` function on Unix /// and the `GetFileAttributesEx` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -827,12 +827,12 @@ pub fn metadata>(path: P) -> io::Result { /// Query the metadata about a file without following symlinks. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `lstat` function on Unix /// and the `GetFileAttributesEx` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -862,12 +862,12 @@ pub fn symlink_metadata>(path: P) -> io::Result { /// /// This will not work if the new name is on a different mount point. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `rename` function on Unix /// and the `MoveFileEx` function with the `MOVEFILE_REPLACE_EXISTING` flag on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -903,14 +903,14 @@ pub fn rename, Q: AsRef>(from: P, to: Q) -> io::Result<()> /// /// On success, the total number of bytes copied is returned. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `open` function in Unix /// with `O_RDONLY` for `from` and `O_WRONLY`, `O_CREAT`, and `O_TRUNC` for `to`. /// `O_CLOEXEC` is set for returned file descriptors. /// On Windows, this function currently corresponds to `CopyFileEx`. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -941,12 +941,12 @@ pub fn copy, Q: AsRef>(from: P, to: Q) -> io::Result { /// The `dst` path will be a link pointing to the `src` path. Note that systems /// often require these two paths to both be located on the same filesystem. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `link` function on Unix /// and the `CreateHardLink` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -998,13 +998,13 @@ pub fn soft_link, Q: AsRef>(src: P, dst: Q) -> io::Result<( /// Reads a symbolic link, returning the file that the link points to. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `readlink` function on Unix /// and the `CreateFile` function with `FILE_FLAG_OPEN_REPARSE_POINT` and /// `FILE_FLAG_BACKUP_SEMANTICS` flags on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1032,12 +1032,12 @@ pub fn read_link>(path: P) -> io::Result { /// Returns the canonical form of a path with all intermediate components /// normalized and symbolic links resolved. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `realpath` function on Unix /// and the `CreateFile` and `GetFinalPathNameByHandle` functions on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1064,12 +1064,12 @@ pub fn canonicalize>(path: P) -> io::Result { /// Creates a new, empty directory at the provided path /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `mkdir` function on Unix /// and the `CreateDirectory` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1097,12 +1097,12 @@ pub fn create_dir>(path: P) -> io::Result<()> { /// Recursively create a directory and all of its parent components if they /// are missing. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `mkdir` function on Unix /// and the `CreateDirectory` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1131,12 +1131,12 @@ pub fn create_dir_all>(path: P) -> io::Result<()> { /// Removes an existing, empty directory. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `rmdir` function on Unix /// and the `RemoveDirectory` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1167,13 +1167,13 @@ pub fn remove_dir>(path: P) -> io::Result<()> { /// This function does **not** follow symbolic links and it will simply remove the /// symbolic link itself. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to `opendir`, `lstat`, `rm` and `rmdir` functions on Unix /// and the `FindFirstFile`, `GetFileAttributesEx`, `DeleteFile`, and `RemoveDirectory` functions /// on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1212,12 +1212,12 @@ fn _remove_dir_all(path: &Path) -> io::Result<()> { /// The iterator will yield instances of `io::Result`. New errors may /// be encountered after an iterator is initially constructed. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `opendir` function on Unix /// and the `FindFirstFile` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// @@ -1315,12 +1315,12 @@ fn next(&mut self) -> Option> { /// Changes the permissions found on a file or a directory. /// -/// # Platform behavior +/// # Platform-specific behavior /// /// This function currently corresponds to the `chmod` function on Unix /// and the `SetFileAttributes` function on Windows. /// Note that, this [may change in the future][changes]. -/// [changes]: https://github.com/rust-lang/rust/pull/28613 +/// [changes]: ../io/index.html#platform-specific-behavior /// /// # Errors /// diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs index 8ac46bf51f1..b5ba6ff54c0 100644 --- 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")]