Add missing code examples

[GuillaumeGomez]

r? @rust-lang/docs

[QuietMisdreavus]

Every doctest failed with something like this:

[01:20:32] ---- os/linux/fs.rs - os::linux::fs::MetadataExt::st_size (line 179) stdout ----
[01:20:32] 	error: unused import: `std::os::unix::prelude::*;`
[01:20:32]  --> os/linux/fs.rs:5:5
[01:20:32]   |
[01:20:32] 5 | use std::os::unix::prelude::*;
[01:20:32]   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^
[01:20:32]   |
[01:20:32] note: lint level defined here
[01:20:32]  --> os/linux/fs.rs:1:9
[01:20:32]   |
[01:20:32] 1 | #![deny(warnings)]
[01:20:32]   |         ^^^^^^^^
[01:20:32]   = note: #[deny(unused_imports)] implied by #[deny(warnings)]
[01:20:32] 
[01:20:32] error[E0599]: no method named `st_size` found for type `std::fs::Metadata` in the current scope
[01:20:32]   --> os/linux/fs.rs:10:21
[01:20:32]    |
[01:20:32] 10 | println!("{}", meta.st_size());
[01:20:32]    |                     ^^^^^^^
[01:20:32]    |
[01:20:32]    = help: items from traits can only be used if the trait is in scope
[01:20:32]    = note: the following trait is implemented but not in scope, perhaps add a `use` for it:
[01:20:32]            candidate #1: `use std::os::linux::fs::MetadataExt;`

From the Cargo invocation that's printed at the end, it looks like it's properly running under the x86_64-unknown-linux-gnu target, and the linux module is tagged with #[doc(cfg(target_os = "linux"))] from that PR. It seems like the MetadataExt trait isn't in that prelude, somehow? This seems off.

[QuietMisdreavus]

Oh! You're trying to use the unix::MetadataExt trait, but all these methods are on the linux::MetadataExt trait.

[GuillaumeGomez]

Ah maybe.

[GuillaumeGomez]

Let's see with this cfg. :)

[kennytm]

o_O Why not just add use std::os::linux::fs::MetadataExt. #[doc(cfg)] should have ensured the doc tests won't run outside of Linux. The issue here is you did not import std::os::linux::fs::MetadataExt.

[GuillaumeGomez]

It's working fine in a code of mine so I don't think this is the issue.

[GuillaumeGomez]

My fix worked!

[QuietMisdreavus]

You just #if 0'd all your code samples. There is no #[cfg(linux)]. The std::os module itself uses #[cfg(target_os = "linux")] to target Linux-specific things.

[kennytm]

This should work, you could adapt it to the examples...

use std::fs;
use std::os::linux::fs::MetadataExt; // <--------------- use this -------------

use std::io;
fn f() -> io::Result<()> {
    let meta = fs::metadata("/dev/null")?;
    println!("{}", meta.st_dev());
    Ok(())
}

fn main() {
    println!("{:?}", f());
}

[GuillaumeGomez]

Updated and working.

[kennytm]

This #[cfg(target_os = "linux")] block could be removed, #[doc(cfg)] should not run the doc tests outside of Linux.

[GuillaumeGomez]

The point is that, if users want to take a look at the full code (by clicking on "run"), they'll see this conditional compilation.

[QuietMisdreavus]

How many people click on "Run" though? I'm thinking of how many people copy out the examples in File and run into "? in main" errors.

[frewsxcv]

no_run?

[QuietMisdreavus]

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.

[QuietMisdreavus]

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

[GuillaumeGomez]

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

[QuietMisdreavus]

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.

[QuietMisdreavus]

Welp, travis passed and i have no idea how. If it's a problem then homu will find it; if it's not a problem then i'll stop worrying about it.

@bors r+ rollup

[bors]

📌 Commit e42da90 has been approved by QuietMisdreavus