Rollup merge of #145290 - ntc2:patch-1, r=joshtriplett,tgross35

Improve std::fs::read_dir docs

Call out early that the results returned can differ across calls / aren't deterministic. This was already mentioned at the bottom of examples, but I think it's worth calling out early, since this caused at least one person (me!) great confusion.

Author: matthiaskrgr

library/std/src/fs.rs

@@ -3036,6 +3036,9 @@ pub fn remove_dir_all<P: AsRef<Path>>(path: P) -> io::Result<()> {
 /// Entries for the current and parent directories (typically `.` and `..`) are
 /// skipped.
 ///
+/// The order in which `read_dir` returns entries can change between calls. If reproducible
+/// ordering is required, the entries should be explicitly sorted.
+///
 /// # Platform-specific behavior
 ///
 /// This function currently corresponds to the `opendir` function on Unix