Add "choosing between walkdir and std::fs::read_dir" section to the docs

[matklad]

Meta: this isn't remotely important, logging the issue just for completeness sake.

In rust-analyzer, I am writing a test that needs to list all Rust files in rust-analyzer's repo. I think in this context using stdlib and doing something like the following should be fine:

fn list_files_recursively(dir: &Path) -> io::Result<Vec<PathBuf>> {
    let mut res = Vec::new();
    let mut work = vec![dir.to_path_buf()];
    while let Some(dir) = work.pop() {
        for entry in dir.read_dir()? {
            let entry = entry?;
            let file_type = entry.file_type()?;
            if file_type.is_dir() {
                work.push(entry.path())
            } else if file_type.is_file() {
                res.push(entry.path())
            }
        }
    }
    Ok(res)
}

However I am not sure -- there might be some pitfalls about std::fs::read_dir I am not sure about (similarly to how, eg, remove_dir_all doesn't always work on Windows). It would be helpful if walkdir (the primary alternative to "do it yourself") docs contained a section explaining when walkdir isn't actually needed.