Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add missing code examples #45361

Merged
merged 2 commits into from
Oct 25, 2017
Merged

Add missing code examples #45361

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3507b2b
Add missing code examples
GuillaumeGomez Oct 18, 2017
e42da90
Fix doc build on other architectures than linux
GuillaumeGomez Oct 18, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
242 changes: 241 additions & 1 deletion src/libstd/os/linux/fs.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
///
/// ```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no_run?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess since all of the examples are secretly function definitions that are never called, it's no difference whether or not no_run is actually there.

/// use std::fs;
/// use std::os::linux::fs::MetadataExt;
///
/// # use std::io;
/// # fn f() -> io::Result<()> {
/// let meta = fs::metadata("some_file")?;
/// let stat = meta.as_raw_stat();
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth adding an example to this method, since it's deprecated?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's always worth it. As long as it's there, it has to be documented.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fair point. I was thinking in terms of "we're suggesting people use other methods, so why do we provide incentive to look at this one?"

Also now that i'm thinking about it, i'm concerned that this may not actually pass tests, since every doctest in std has deny(warnings) applied to it. If this passes travis, i'll let it slide, but that's at least my reasoning.

/// # Ok(())
/// # }
/// ```
#[stable(feature = "metadata_ext", since = "1.1.0")]
#[rustc_deprecated(since = "1.8.0",
reason = "deprecated in favor of the accessor \
Expand All @@ -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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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::linux::fs::MetadataExt;
///
/// # 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;
}
Expand Down