Docs: add corner cases of Path::file_name()

[marcospb19]

Documenting corner cases where Path::file_name() returns None, and adding examples.

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @Mark-Simulacrum (or someone else) soon.

Please see the contribution instructions for more information.

[marcospb19]

Here's the page rendered:

This markdown list is looking kinda squished and confusing, maybe I should just throw these corner cases in the doc test assertions? And remove the "(e.g. ...)" examples.

[jfrimmel]

Maybe this isbbetter (remove quotes in favor of only markdown code blocks)?

[marcospb19]

@jfrimmel I do think it looks weird:

"Terminates in ..." looks like 3 dots, instead of 2.

I will also add "(double dots)" to the side of it, to see if it helps.

[marcospb19]

Here's the current status:

[Mark-Simulacrum]

I think this is missing the Prefix variant of Component -- maybe it is more useful to say "returns None if the last component of the path is not Normal" and link to https://doc.rust-lang.org/nightly/std/path/enum.Component.html?

[marcospb19]

That's a great idea, however, here is the documentation of Component:

It does not explain that running components on "a/." gives Component::Normal("a") instead of Normal("a") AND CurrrentDirectory, plus I think people are expecting "asd/.".file_name() to return ".", so, maybe this should be explained somewhere?

Maybe I could add examples to the docs of Component itself to show what iterating on Path::new("/a/b/c") retrieves, then we could also cover this corner cases.

However, there is already something like this at https://doc.rust-lang.org/nightly/std/path/struct.Path.html#method.components.

use std::path::{Path, Component};
use std::ffi::OsStr;

let mut components = Path::new("/tmp/foo.txt").components();

assert_eq!(components.next(), Some(Component::RootDir));
assert_eq!(components.next(), Some(Component::Normal(OsStr::new("tmp"))));
assert_eq!(components.next(), Some(Component::Normal(OsStr::new("foo.txt"))));
assert_eq!(components.next(), None)

So, maybe I should add more examples to path::components instead? Or add some explanation in the Component page itself.

Waiting for some feedback on these thoughts.

[Mark-Simulacrum]

I think adding more docs to Component makes sense, since it's a dedicated page for this. We can point there from file_name() and potentially components() as well.

[marcospb19]

Nice, I agree! I've been getting very busy this days, so I might need to delay this PR just a couple weeks, but thanks for the review.

[Dylan-DPC]

@marcospb19 any updates on this?

[marcospb19]

@Mark-Simulacrum @Dylan-DPC sorry for the huge delay on this, I'm struggling with managing my personal time.

Was not able to finish this yet.

If someone want to open a PR with it finished, I'd be glad, you might want to close mine.

(Or commit on my branch, for some repo member).

[Dylan-DPC]

@marcospb19 that's totally fine and understandable. I'll close this for now, thanks for taking the time to contribute to rust.