os: document DirFS implements fs.StatFS

[wbourne0]

What version of Go are you using (go version)?

$ go version
go version go1.18 linux/amd64

The change which added .Stat

Does this issue reproduce with the latest release?

Yes - this issue exists in >=17 (change to implement fs.StatFS introduced here)

What operating system and processor architecture are you using (go env)?

n/a

What did you do?

https://go.dev/play/p/PdBdag3nnUd

Use .Stat on the result of os.DirFS.

What did you expect to see?

The program should compile and stat the file.

os.DirFS should return fs.StatFS instead of a fs.FS as os.dirFS implements fs.StatFS.

Same result as it would be if manually casting to fs.StatFS - https://go.dev/play/p/2T4F9981gzE?v=gotip

What did you see instead?

./prog.go:12:17: fs.Stat undefined (type fs.FS has no field or method Stat)

Go build failed.

There might be a reason for os.DirFS returns fs.FS instead of fs.StatFS but I didn't see any comments on the change introducing it that mentioned one.

[seankhliao]

Changing the return type of os.DirFS would be a breaking change.
The additional interfaces of io/fs are meant as extensions to be tested for before being used (that's why each only defines a single extra method).

[gopherbot]

Change https://go.dev/cl/394555 mentions this issue: os: document DirFS implements fs.StatFS