From 3507b2b26b65127f8bee922d5a97dcce9415381a Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 18 Oct 2017 13:58:53 +0200 Subject: [PATCH 1/2] Add missing code examples --- src/libstd/os/linux/fs.rs | 242 +++++++++++++++++++++++++++++++++++++- 1 file changed, 241 insertions(+), 1 deletion(-) diff --git a/src/libstd/os/linux/fs.rs b/src/libstd/os/linux/fs.rs index 7ebda5ed744fd..a406bff92c2a4 100644 --- a/src/libstd/os/linux/fs.rs +++ b/src/libstd/os/linux/fs.rs @@ -24,9 +24,25 @@ pub trait MetadataExt { /// Gain a reference to the underlying `stat` structure which contains /// the raw information returned by the OS. /// - /// The contents of the returned `stat` are **not** consistent across + /// The contents of the returned [`stat`] are **not** consistent across /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the /// cross-Unix abstractions contained within the raw stat. + /// + /// [`stat`]: ../../../../std/os/linux/raw/struct.stat.html + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// let stat = meta.as_raw_stat(); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext", since = "1.1.0")] #[rustc_deprecated(since = "1.8.0", reason = "deprecated in favor of the accessor \ @@ -35,54 +51,278 @@ pub trait MetadataExt { fn as_raw_stat(&self) -> &raw::stat; /// Returns the device ID on which this file resides. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_dev()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_dev(&self) -> u64; /// Returns the inode number. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_ino()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_ino(&self) -> u64; /// Returns the file type and mode. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_mode()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_mode(&self) -> u32; /// Returns the number of hard links to file. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_nlink()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_nlink(&self) -> u64; /// Returns the user ID of the file owner. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_uid()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_uid(&self) -> u32; /// Returns the group ID of the file owner. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_gid()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_gid(&self) -> u32; /// Returns the device ID that this file represents. Only relevant for special file. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_rdev()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_rdev(&self) -> u64; /// Returns the size of the file (if it is a regular file or a symbolic link) in bytes. /// /// The size of a symbolic link is the length of the pathname it contains, /// without a terminating null byte. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_size()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_size(&self) -> u64; /// Returns the last access time. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_atime()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_atime(&self) -> i64; /// Returns the last access time, nano seconds part. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_atime_nsec()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_atime_nsec(&self) -> i64; /// Returns the last modification time. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_mtime()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_mtime(&self) -> i64; /// Returns the last modification time, nano seconds part. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_mtime_nsec()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_mtime_nsec(&self) -> i64; /// Returns the last status change time. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_ctime()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_ctime(&self) -> i64; /// Returns the last status change time, nano seconds part. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_ctime_nsec()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_ctime_nsec(&self) -> i64; /// Returns the "preferred" blocksize for efficient filesystem I/O. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_blksize()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_blksize(&self) -> u64; /// Returns the number of blocks allocated to the file, 512-byte units. + /// + /// # Examples + /// + /// ``` + /// use std::fs; + /// use std::os::unix::prelude::*; + /// + /// # use std::io; + /// # fn f() -> io::Result<()> { + /// let meta = fs::metadata("some_file")?; + /// println!("{}", meta.st_blocks()); + /// # Ok(()) + /// # } + /// ``` #[stable(feature = "metadata_ext2", since = "1.8.0")] fn st_blocks(&self) -> u64; } From e42da901a8f1192aa66ee8d8fbf3ebd9ade95062 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 18 Oct 2017 18:39:44 +0200 Subject: [PATCH 2/2] Fix doc build on other architectures than linux --- src/libstd/os/linux/fs.rs | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/src/libstd/os/linux/fs.rs b/src/libstd/os/linux/fs.rs index a406bff92c2a4..5d37d970e89b6 100644 --- a/src/libstd/os/linux/fs.rs +++ b/src/libstd/os/linux/fs.rs @@ -34,7 +34,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -56,7 +56,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -73,7 +73,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -90,7 +90,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -107,7 +107,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -124,7 +124,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -141,7 +141,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -158,7 +158,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -178,7 +178,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -195,7 +195,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -212,7 +212,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -229,7 +229,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -246,7 +246,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -263,7 +263,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -280,7 +280,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -297,7 +297,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> { @@ -314,7 +314,7 @@ pub trait MetadataExt { /// /// ``` /// use std::fs; - /// use std::os::unix::prelude::*; + /// use std::os::linux::fs::MetadataExt; /// /// # use std::io; /// # fn f() -> io::Result<()> {