Documentation for std::path::PathBuf::pop is slightly wrong

[nathan]

The documentation for std::path::PathBuf::pop() says:

Returns false and does nothing if self.file_name is None. Otherwise, returns true.

However, self.file_name() is None when the path ends in ..—but pop() still does removes that component and returns true. The docs should probably be changed to reflect that pop() truncates and returns true unless self.parent() is None.

use std::path::PathBuf;

fn main() {
  let mut p = PathBuf::from("/foo/bar/..");
  println!("{:?} {:?}", p.display(), p.file_name());
  println!("{:?}", p.pop());
  println!("{:?} {:?}", p.display(), p.file_name());
  println!("{:?}", p.pop());
  println!("{:?} {:?}", p.display(), p.file_name());
  println!("{:?}", p.pop());
  println!("{:?} {:?}", p.display(), p.file_name());
  println!("{:?}", p.pop());
  println!("{:?} {:?}", p.display(), p.file_name());
}

(Playground)

Output:

"/foo/bar/.." None
true
"/foo/bar" Some("bar")
true
"/foo" Some("foo")
true
"/" None
false
"/" None

[hellow554]

@nathan would you open a PR and edit the required paragraph? Seems to be an easy issue :)

https://github.com/rust-lang/rust/blob/master/src/libstd/path.rs#L1231-L1261

[nathan]

@hellow554 Sure thing! #58496