io/ioutil: provide an equivalent for the deprecated ReadDir

All APIs in the now-deprecated io/ioutil package have a direct
replacement in either the io or os package with the same signature,
with the notable exception of ioutil.ReadDir, as os.ReadDir has a
slightly different signature with fs.DirEntry rather than fs.FileInfo.

New code can easily make use of []fs.DirEntry directly,
but existing code may need to continue using []fs.FileInfo for backwards
compatibility reasons. For instance, I had a bit of code that exposed
the slice as a public API, like:

	return ioutil.ReadDir(name)

It took me a couple of minutes to figure out what the exact equivalent
in terms of os.ReadDir would be, and a code sample would have helped.
Add one for future reference.

For #42026.
For #51927.

Change-Id: I76d46cd7d68fc609c873821755fdcfc299ffd56c
Reviewed-on: https://go-review.googlesource.com/c/go/+/399854
Reviewed-by: Bryan Mills <[email protected]>
Run-TryBot: Bryan Mills <[email protected]>
TryBot-Result: Gopher Robot <[email protected]>
Reviewed-by: Ian Lance Taylor <[email protected]>
Run-TryBot: Ian Lance Taylor <[email protected]>
Auto-Submit: Ian Lance Taylor <[email protected]>

src/io/ioutil/ioutil.go

@@ -55,6 +55,17 @@ func WriteFile(filename string, data []byte, perm fs.FileMode) error {
 // it returns a list of fs.DirEntry instead of fs.FileInfo,
 // and it returns partial results in the case of an error
 // midway through reading a directory.
+//
+// If you must continue obtaining a list of fs.FileInfo, you still can:
+//
+//	entries, err := os.ReadDir(dirname)
+//	if err != nil { ... }
+//	infos := make([]fs.FileInfo, 0, len(entries))
+//	for _, entry := range entries {
+//		info, err := entry.Info()
+//		if err != nil { ... }
+//		infos = append(infos, info)
+//	}
 func ReadDir(dirname string) ([]fs.FileInfo, error) {
 	f, err := os.Open(dirname)
 	if err != nil {