Rollup merge of #105745 - philpax:patch-1, r=jyn514

docs(std): clarify remove_dir_all errors

When using `remove_dir_all`, I assumed that the function was idempotent and that I could always call it to remove a directory if it existed. That's not the case and it bit me in production, so I figured I'd submit this to clarify the docs.

Author: matthiaskrgr

library/std/src/fs.rs

@@ -2284,6 +2284,11 @@ pub fn remove_dir<P: AsRef<Path>>(path: P) -> io::Result<()> {
 ///
 /// See [`fs::remove_file`] and [`fs::remove_dir`].
 ///
+/// `remove_dir_all` will fail if `remove_dir` or `remove_file` fail on any constituent paths, including the root path.
+/// As a result, the directory you are deleting must exist, meaning that this function is not idempotent.
+///
+/// Consider ignoring the error if validating the removal is not required for your use case.
+///
 /// [`fs::remove_file`]: remove_file
 /// [`fs::remove_dir`]: remove_dir
 ///