Add examples for GenericPath methods.

[nham]

I wanted to use assert_eq throughout, but that does not seem possible (see #15625)

[alexcrichton]

I believe that paths are internally normalized, so this test (and ones below) may fail on windows due to / being normalized to \. I don't think we currently run doc tests on windows, but this may surprise someone at some point.

[lilyball]

That's correct. This is going to affect all of the examples that test the value of the path.

[nham]

Is the fix here to use PosixPath instead of Path? Or does that affect anything?

[alexcrichton]

You can use path::SEP, but I would avoid PosixPath in the GenericPath documentation.

[lilyball]

Perhaps you could document at the module level that all the examples are written assuming unix?

@alexcrichton Do we have a tag for code blocks to skip them under Windows? You said we don't run doc tests on Windows right now but presumably that will change at some point.

[alexcrichton]

You could sneak around it like this:

/// ```
/// #[cfg(not(windows))]
/// # fn foo() {
/// ... dox dox dox
///
/// ... dox dox dox
/// # }
/// # #[cfg(windows)] fn foo() {}
/// # foo()
/// ```

[lilyball]

That seems like a lot of effort to put in each example.

[alexcrichton]

I left a now-hidden comment, but an icky but hidden-from-the-user strategy for dealing with windows may be something like this:

/// ```
/// # foo();
/// # #[cfg(windows)] fn foo() {}
/// # #[cfg(unix)] fn foo() {
/// ... dox dox dox
///
/// ... dox dox dox
/// # }
/// ```

[nham]

As for using path::SEP instead of e.g. "foo/bar", is there a nice way to do this? The best I've come up with is:

"foo".to_string() + SEP.to_string() + "bar"

It's not horrible, but seems a bit icky. Alternatively, could I use join everywhere instead?

[alexcrichton]

It'd be some extra boilerplate required for the cfg(windows) or not, but in terms of documentation I think it's higher quality than to_string() and friends (it also passes tests on all platforms)

[nham]

I just attempted to implement skipping the doc tests for windows. Hopefully I've done that correctly